What is an API?
To spell it out more plainly, API stands for “application programming interface.” But even after spelling it out, it may still cause confusion. An API is one piece of software talking to another, or one system talking to another system. In its simplest form, it's a structured request with a structured response. An API is like a contract that includes an understanding between both parties and an agreed-upon standard set by which those parties communicate.
Think of this analogy: if you’re a customer at a restaurant you have a menu of items you can order. Pretend that you, as the customer, are the application making the request. You make the request to the waitstaff - pretend that they are the API. The waitstaff, aka the API, brings the request to the kitchen (or the FileMaker Server), where the request is processed. The kitchen makes your food and then once the food is complete, it goes back through the waitstaff (or your API), and then you receive your food (or your response).
If you have ever worked with the FileMaker Web Viewer Setup window, there are predefined URL’s listed in the “Choose a Website” option, and one of those is an ability to talk to FedEx. This is an example of a simple API integration pre-built into FileMaker. FileMaker is taking your request, sending the request to the FedEx API, and then returning a response.
When you enter a tracking number, FileMaker sends that to the FedEx API which returns a URL that contains the tracking details or delivery status. FileMaker interprets that as an actual URL that will display in the web viewer like any other web page.
The FedEx URL might look something like this:
The web viewer displays the URL as a web page:
API Consumers and Providers
There are two sides to the API equation. First, there’s the idea of an API consumer - this can come in the form of a mobile phone, a website, or even FileMaker Pro Advanced. This is the ability to consume information through an API. You can create your own requests, reach out to an API, and get information back.
On the other side of the equation, is the provider (providing the response). As in the case above, FedEx provided the URL for the tracking number. There are many providers such as Google Maps, YouTube, Stripe, MailChimp, and DocuSign.
Some can be both. For example, the FileMaker platform offers both sides of the equation – it is both a consumer and a provider of APIs. In the web viewer example, FileMaker Pro was acting as the consumer. With the FileMaker Data API or Admin API, you can send requests for FileMaker data and information.
There are many entities that have an API you can talk to, post a request, and gather information. Below are examples for various companies and industries with API capabilities but many more exist. Some APIs are simple and easy-to-use, but some can be complicated. It is also important to know that not all API connections are free.
Examples of social media APIs:
- YouTube
Examples of database and CRM APIs:
- AWS
- Salesforce
- Infusionsoft
- Microsoft Dynamics
In the web e-commerce world, there are many different web shopping carts. A lot of them are great at taking orders, but not a lot of them are good at managing customers or inventory. Therefore, integrating the e-commerce API with FileMaker allows you to gather your order data and then manage the rest of the details in FileMaker. We think that it's essential that a shopping cart has an API that developers can talk to, pull information down, or push products out. Examples include:
- BigCommerce
- Wix
- Shopify
On the business side, there are examples such as:
- Dropbox
- OneDrive
- Survey Monkey
- Mailchimp
- Google (they offer many API options)
- Microsoft
API Security: Authentication and Authorization
Security is a big part of today's world and everything that we do. Most APIs use world-class security in order to talk to them. As you learn how to work with APIs, you’ll discover that API keys and API security are the most difficult development concepts and steps to understand. Before we go any further, we need to define two terms: authentication and authorization.
Authentication is the idea that we're going to identify who you are. Do you have an account? Do you have the privileges to gain access to this information? That could come in the form of username and password or an API key. Authentication is not to be confused with authorization, which is what happens after you get approval to be in a system. This tells you what you are allowed (authorized) to do once you have been authenticated.
Think about our restaurant analogy again. If you ask for an adult beverage and don't look old enough, you'll be asked for an ID (this is the authentication request). The waitstaff will review the ID – do you look like the picture on the ID? Are you over the age of 21? Confirming these details authenticates you. The next step is authorization. Now that they know you're 21 or older, you're authorized to order an adult beverage at the restaurant. APIs work a lot like this.
API Security Methods
There are four basic methods of API security that we will cover.
- Open API
- HTTP basic
- API Keys
- OAuth
Open API (No Security)
“No security” is the first and easiest to understand. There are no passwords, no keys, no tokens; it is simply open to any request and known as an Open API. You have no authentication or authorization. In the FedEx example, there was no request for a username or password. You simply put in the shipping tracking number, and FedEx sent a response. That is an example of no security.
Google Maps is another example. It does not ask you for your username and password when you put in an address. Or if you use Weather Underground to get the weather for a particular location, you simply put in the zip code to get access to the weather.
HTTP Basic
The next form of security is called HTTP Basic which is the process of simply asking for username and password for the API authentication. As you can imagine, this does not provide a lot of security, but it is still used today under certain circumstances, with older APIs or on private networks. It is important to remember that if you are not using an SSL certificate, then the username and password is being transmitted over open/unsecure lines. When APIs first came out, a username and password were pretty much all you needed, but more robust and secure options are now available.
Examples of HTTP Basic include GitHub, which is a repository for software developers and Slack, which is a communications tool.
API Keys
You've probably heard the term, API Key, but may not fully understand what it means. An API key is traditionally a very long string of code. It's usually unique, hard to guess, and is distributed by the API provider for security.
The advantage of an API key is that it doesn't necessarily need to be tied to a user. You can grant access to an entire workforce, a system, or website using one API key without heckling each user for individual credentials.
API providers may have different methods of obtaining and storing the API key. Typically, the API provider will assign you a unique API key that you then copy and paste into your app or code.
API keys are used with Dropbox, Mailchimp, Stripe, AWS and many other APIs.
OAuth
OAuth stands for open authentication. This is the modern, most secure, and most flexible way of handling security through APIs. What makes this even more important than all the other forms of security listed here is that the user can securely gain access through a third-party application without jeopardizing their credentials. The majority of new or existing APIs are trending toward implementing OAuth security.
Where HTTP Basic would use a username and password and API Keys are generated once by the API provider, OAuth uses dynamically generated authorization tokens for limited periods of time to allow access to the API.
It’s extremely useful if you are building a system with a group of users but you don’t know any of their credentials, you’ll know that specific group can still be allowed to work with your API.
If you remember the example of ordering the food and then the adult beverage, your ID has been checked and allows you to order drinks. But let’s take this a step further. Let’s say you’re at a festival and you don't want to show your ID each time you get an adult beverage. You might receive a wristband for the day of the festival, or in this case, a token. This authorizes you to purchase drinks all day long.
Examples of APIs that use OAuth are QuickBooks Online, the Google APIs, and many of the Microsoft products, Office 365, etc.
API Terms to Know
There are a few terms that are important to define in the API documentation:
Methods: Methods refer to the HTTP methods that an API will require. There are many types of HTTP methods, but these are the common ones:
- GET: Retrieve data from a specified resource
- POST: Submit data to be processed to a specified resource
- PUT/PATCH: Update a specified resource (needs ID)
- DELETE: Delete a specified resource (needs ID)
Endpoints: When an API references a resource, it often declares it in an “endpoint”. An endpoint is essentially the end tail of a URL and is considered a logical grouping of resources belonging to the API. For instance, if an API allows users to request a list of customers, it will provide an endpoint for customers, and the endpoint would require a “GET” HTTP method.
API Calls: There are three essential components of an API call:
- Part one: the URL and the endpoint which are combined as one string.
- Part two: the header
- Part three: the body
Just about every API call that you can think of uses this combination of things to get started. All of this information should be available in the documentation you get with the respective API.
Pulling it all Together – a Simple API Call
Let’s look at an example of an API call: getting the general server settings from FileMaker Server’s Admin API. Below is a breakdown of the HTTP Method, the URL, Endpoint, and the list of headers associated with the request.
Method: GET
URL: https://pculearning.com/fmi/admin/api/v2
Endpoint: /server/config/general
Header:
--header "Authorization: Bearer <<token>>"
--header "Content-Type: application/json"
The URL references the API’s primary server location, the Endpoint references the specific command we want to perform in the API, and the Header contains all appropriate request header information such as the authorization token, body content type, what type of data to expect, etc., as needed.
If we look at a bit of scripting from FileMaker, we see that the script step “Insert from URL” provides numerous options and is the powerhouse of accessing an API. This script step allows the use of cURL, a common and widely supported communication technology, for interacting with numerous web-based resources such as the FileMaker Admin API. Within this step, we make several configuration changes:
- Target: Set the target field or variable for the results to be stored into (this is standard for most script steps; in our example, we use $result as the target)
- Specify URL: Set the URL and endpoint of the API to communicate with
- Verify SSL Certificates: Indicates whether to force verification of an API’s SSL certificates (this can often be ignored, but may be necessary if SSL is required by the API)
- Specify cURL options: Set any cURL options here, including the HTTP method, header information, body data, etc. This is the most important script step option when communicating with an API, as this is where “all the magic happens”
If all of the settings above are accurate and as the API requires, the result of the Insert from URL script step will be placed where the Target dictates; if we use our earlier example, we should receive all of the general settings of the FileMaker server in the $result variable.
There is much more to discuss about API requirements, including whether to use XML or JSON for the body data, what different kinds of APIs need in their headers, what a RESTful API is all about, and so on, but we’ll save that for another blog!
Learn how to connect FileMaker to APIs
For more information on working with APIs have a look at the online training courses we have available at Productive Computing University.
The API Fundamentals for FileMaker Developers is a great starting point. This course covers how APIs work, JSON formatting, common use cases, how to set up the connection, prepare API calls, and parse responses. Most importantly, you'll learn to work directly with the FileMaker Data API.
- API DevCon Session: This free recording of “How to Understand the Basics of API” session reviews the basics from this blog and more!
- Twilio: The Connect FileMaker to Twilio course will walk you through the process of sending text messages (SMS and MMS) by integrating FileMaker with the Twilio API.
- Mailchimp: The Connect FileMaker to Mailchimp API course will show you how to integrate a FileMaker solution with several modules in Mailchimp so you can control data flow, accuracy, and productivity.
- Stripe: In our course Connect FileMaker to Stripe API, you learn how to work with data from a Stripe account for reporting, tracking, integration, and processing payments.
- Charting and Tableau: Our FileMaker Charting and Beyond course is created specifically for developers needing to demystify the fundamentals of FileMaker charting. We show you how to create and configure all 10 of the different FileMaker charts and demonstrate using an API connection to the free version of Tableau.
Free API Video Resources
If you are interested in additional FileMaker API videos and training, we have a number of free videos available on our YouTube channel:
Learn how we can help you started with using APIs with FileMaker.
Get weather updates in FileMaker with this free API and sample file.
Additional Resources
If you are interested in additional FileMaker videos, training courses or product news, please:
- Subscribe to our YouTube channel for FileMaker tips and tricks. If you liked this post, make sure to check out our FREE API playlist on YouTube as well.
- Subscribe to our newsletter for industry and product updates
- Check out Productive Computing University for in-depth training courses covering advanced FileMaker technologies such as FileMaker Certification exam preparation, API integrations, working with QuickBooks, FileMaker Charting, and much more.
-
Have a look through our blog posts. If you liked this recap of API integrations, consider reading some of our other blogs.
