Beer can be brewed to perfection, but it’s up to the consumer to enjoy the golden liquid up to its very last sip. The same principle is true for APIs. The consumer of APIs has little influence on how APIs are designed but can shape how to consume the APIs.

So, let’s sit down, and see what consuming APIs and beers have in common. It does not seem to be a coincidence that the most popular beer style in the US in the year 2020 was an IPA (API backward…).

Common use cases for MFT APIs

It all starts with a use case. A need to query an API of your MFT solution. A need that goes above operating a nicely designed User Interface.

Just to name a few commonly requested and implemented use cases I have seen in the past years across MFT customer base:

• Create a regular report for auditing purposes on configuration summaries, transfer activities, or administrative accesses.
• Mass update of configuration settings, such as replacing an expired key for several occurrences of a transfer site. The same works with an IP address, password, or other details that are prone to frequent changes.
• Adhoc triggers or scheduled tasks, such as pulling files from a partner or uploading a trigger file to actuate further processing of events.
• The request of a file transfer status for alerting or reporting purposes.
• Onboarding of new partners or flows during large-scale migration projects.
• Automate the deployment of new application nodes.
• Providing self-service capabilities for users or delegated administrators for re-occurring tasks such as resetting passwords, updating certificates, or enabling new partners ideally fully integrated into customer’s existing IT management solutions.
• Automate operational processes such as synchronizing or bouncing cluster nodes or changing database connection strings in a failover scenario.
• Monitor the status of the protocol daemons.

The list continues, but we don’t want our beer to continue to get warm.

Next, we look into how the usage of APIs can be made most efficient and valuable for the consumer. Remember the consumer cannot influence the APIs themselves, only how to consume them.

Best practices when consuming APIs: specify the result format

Most APIs can present their result body in different formats. Most widely used are JSON or XML. XML isn’t widely supported by frameworks without transforming the data to something that can be used more commonly, and that is usually JSON.

So best to make your MFT solution return the result set in JSON, not XML. Most server-side technologies have libraries that can decode JSON without doing much work. Specify the expected format in your header with Accept: application/json.

Don’t let the server make the choice of how your response body is formatted.

Make use of Filtering, Sorting, and Pagination

The databases of your MFT solution can get very large. Remember that this is what’s behind your REST API. Always use filters on fields to limit the number of returned results.

Sometimes, there’s so much data that it shouldn’t be returned all at once because its response would be way too slow, will slow down your MFT system, or evaluating the response would impact the client-side.

Therefore, always try to filter the items your REST call is querying. Most APIs provide field search (for example, only return accounts with UID=6000: GET /accounts?uid=6000) or field filtration (for example, only return the UIDs of all accounts: GET /accounts?fields=uid).

Of course, you can use a combination of both. As more data accumulates in the database, the more important these features become.

If you are not sure how much data will be returned, keep in mind that a well-designed API response body should include an attribute such as which contains the number of queried items and total items returned. Use this feature to decide on filter and pagination options.

Pagination

Pagination is a great way to only return a few results at a time. We do not want to tie up resources for too long by trying to get all the requested data at once.

Most APIs offer a parameter to limit the number of returned results, and an offset to create pagination. If the limit parameter is not set, a global server configuration parameter can be configured as a safety net.

Always try to optimize performance

For the most part, the wide adoption and usage of APIs will depend on performance. Poor performance on the client side or performance impact on the server side should be avoided by any means.

One tip to avoid unnecessary resource consumption on the server-side when running a chain of API calls is to make use of session management.

Session management consists of first calling a login API to get authenticated, then performing your normal process, finally closing the session with a log-out API.

To log in to a session, simply call the POST method API /myself and retain your session cookie in a local file. Subsequent APIs reference the same session cookie and no authentication, and the accompanying overhead is required.

Another tip

Another tip to improve performance is to use caching on the client side to return data from a local memory cache instead of querying the server’s database to get the data every time we want to retrieve some static data.

The advantage of caching is that users can get results faster. However, the data may be outdated. Therefore, always consider what data to cache and how long to cache for.

Last but not least…

Last but not least, consider the components that are most utilized when calling an API. First and foremost, API queries utilize the web service of your MFT component.

Allocate enough resources for this component. In scenarios where users query or post a lot of data that interacts with the database, make sure to have a fast and efficient connection to the underlying database.

In scenarios where you expect many simultaneous queries from different users, session management as explained above does not provide much relief for your MFT server.

Instead, adapt server resources to process simultaneous authentication and authorization. Also schedule tasks that are not time-sensitive, such as reports, at times where the server is least busy.

Maintain good security practices

Security should always be your top priority. Therefore, using SSL/TLS for security is a must. The MFT solution by default TLS encrypts all HTTP traffic to the administration web server. Allowing plain HTTP requests to end-user APIs is never recommended.

Equivalent to any access through your administrative user interface, users should not be able to access more information than they need.

For example, a normal user should not be able to access information belonging to another user. Try to limit access to as few resources as needed by enforcing the principle of least privilege.

Try avoiding shared data when not necessary and full administrative access. Using personalized accounts helps with auditing, transparency, and accountability.

When accessing the API, a user must always present some sort of authentication. This can happen in form of a password, a certificate, or even both.

If set up on your MFT solution, the API user can even authenticate against an external Identity Provider or using OAuth. When using Basic Authentication (encoded username and password are passed in the header of your API call) make sure to only ever use HTTPS.

The choice of how a password is stored on the client side is playing a huge role in avoiding having accounts and passwords compromised. Consider using a REST client that allows you to safely encode passwords or supports certificate authentication and stores certificates in a secure key store.

Know your HTTPS status codes

Some APIs are not intended to return a result body. Think about an API to create a new account, update a setting or perform an action on a transfer, those operations do not necessarily require a key-value pair returned to the client. In these cases, it is important to listen to and understand the returned response code from the server.

Let us take an example where you want to create an account, but this account already exists. The authentication is successful, the syntax of the API call is correct, but simply the account already exists.

So, on the server side, nothing had been done or updated. As you see, when using an API, it is essential to understand the returned status code to decide what to do next.

In our example here, the client should consider using an update method to make sure possibly new settings for the already existing account are actually updated on the server-side and not just ignored.

When handling security errors in an API, it is very easy to get confused about whether the error relates to authentication or authorization (a.k.a. permissions). The HTTP status code can easily help to identify the reason for the failure.

Here are some of the most common HTTP status codes:

• 200 OK (mostly for GET or DELETE operations)
• 201 Created (the request has succeeded, and a new resource has been created as a result of it)
• 204 No Content (the server has fulfilled the request but does not need to return an entity-body, and might want to return updated meta-information, mostly for PUT operations)
• 400 Bad Request (server could not understand the request due to invalid syntax)
• 401 Unauthorized (incorrect login credentials)
• 403 Forbidden (insufficient permissions to perform the operation)
• 404 Not Found (the server has not found anything matching the Request-URI)
• 409 Conflict (possibly a duplicate entity)
• 500 Internal Server Error (the server encountered an unexpected condition that prevented it from fulfilling the request)

Pay attention to the version

A REST API is a safe interface, meaning it does not change as long as you keep using the same URI. Of course, there will be evolvement in the functionality and capabilities of APIs with time. This is when versioning plays an essential role.

Always pay attention to the version of APIs that you want to consume. Be aware of version changes on the server side and always consider using the most recent version.

If you just get started with APIs using the latest version of available APIs is highly recommended. The most current APIs are also most likely closely bundled with the most current application version.

Conclusion and how to consume beer

The most important takeaway for consuming APIs is that the client cannot influence how the APIs are designed. But by following some of the discussed principles, performance, ease of usage, and security can be improved or even enforced.

That allows eventually for a wider adaption of APIs and expansion of the MFT service across your own business unit and your partners.

These principles are the first step to a full API management solution. If you think about scaling the usage of APIs, API management solutions can help you in various ways.

They allow you to orchestrate several API, create re-usability, control access and security for APIs and generate metrics and perhaps the possibility of mash-up with other APIs in your enterprise could build new applications that could not have existed before.

So, what do we learn from those best practices when consuming beer?

(Specify the Result Format) It all starts with your choice of beer style. Chose the beer style you like best or will be most popular by your fellow drinkers.

If you are settled on your choice of style, make sure to ask explicitly for the style of beer you want to consume, like an IPA or Stout. Don’t be vague, be specific, and don’t just ask for a “beer.” Otherwise, the result might be unexpected, or even disappointing (ever took a sip of Coors Light when expecting a nice IPA?).

Remember, don’t let the server (the one behind the bar this time) make the choice of what beer he or she will pour you.

(Make use of Filtering, Sorting, and Pagination)

Once settled on your style, decide how the beer should be presented to you and how much you want to consume or buy at once.

Most places will happily serve you a pitcher or a pint of your favorite refreshment. Whereas it might be the easiest way to order, it might not be the best way to preserve the flavor of your beer until the last sip or it might not even be the proper way to enhance the flavor from the very beginning.

Instead, ask for a fresh pour from the tap into the proper glassware. That allows you to enjoy the beer while it is fresh. It is always better to pour in smaller glasses and ask for a second round. Most beer is best when consumed fresh, so buy in small batches and only what you can consume.

(Always try to Optimize Performance)

With time, most people like a certain beer, a style of beer, or even a brewery. The best way to ensure you don’t have to memorize your last beer and whether you liked it or not is simply keeping track of those beers.

Just imagine how quick and efficient you can select your beer next time from a huge choice of taps, if only you had a record of your last consumed beers accessible fast and easy.

Believe it or not, you can use a small old-fashioned notebook for that or keep track using one of the various apps available.

Of course, if you want the fastest and freshest draft beer, don’t order your beer during peak times, you might have a long wait and it will sit on the counter for too long before being delivered to your table. But that seems nearly too obvious to even mention.

(Maintain Good Security Practices)

Before consuming your beer, no matter if you buy it in your local liquor store or brewery, you are most likely asked to present your ID.

Even if you are a known, returning customer, you should always be asked for some sort of authentication. This shows that the seller takes their responsibility very seriously.

Overall, doesn’t that give you a better feeling, that this sense of responsibility will also be reflected in the quality of the beer? That brings us the right to the next topic. Only trust a beer whose source you can verify. It would not occur to you to drink a beer from a glass that you find just sitting on the counter.

Who is it from, what is in it, how long has it been sitting there for? You probably wouldn’t buy a beer from a can that has no label on it, with no information about the brewery or the content itself.

(Pay Attention to the Version)

Always be aware of the year or even the batch of the beer you are drinking. Just because you liked it last time, does not mean, taste and flavor are the same this year. There might be some changes in the recipes to improve the flavor or go with the demand of the consumers and new trends. This is Astrid Fischer, your IPA-loving API, and MFT expert.