API Management: 11 Best Practices for Developers

When formatting your API, be sure to keep in mind industry preferences that improve usability. For example:

• • • Limit verb use — HTTP-based APIs use methods, or verbs, to specify the type of action being performed. In order to minimize confusion and prevent error, it’s ideal to limit verb usage to the four common methods: GET, POST, DELETE, and PUT. Sticking with standardized language helps ensure clear communication between the client and server. In general, nouns should be used instead of verbs whenever possible, as they’re less prone to proliferation. Additionally, verbs tend to be implied by the publicly vetted HTTP protocol.

• • • End all endpoints with nouns — It’s particularly important that you end your endpoints with nouns rather than verbs, as you want to refer to resources rather than actions. Nouns should be singular when the request applies to a single resource member, and plural when the request applies to the collection of resource members (for example, API/customer when requesting information about a particular customer, API/customers when requesting information about two or more customers at the same time).

• • • Use JSON instead of XML — JSON has become the preferred format for web APIs. It has a much simpler structure and syntax, making it easier for human users to understand.

For maximum security, API calls should be made over an SSL-encrypted HTTP connection, or HTTPS. The use of this more secure protocol ensures that all data is encrypted before being sent between the client and server.

Clients should be able to easily view and locate data points that are returned on a call.

Endpoints will often return a lot of data unless specified otherwise, so it’s important that clients can pinpoint data with ease. Be sure that your API allows clients to parse through data by:

• • • Filtering: applying set parameters or criteria to narrow down data
    • Sorting: choosing how to display results (e.g., ascending or descending), and by which attributes
    • Pagination: viewing results on several separate, sequential pages

Just as software is constantly enhanced over time, your API will also evolve. And when changes are made, it’s essential that the API continues to remain functional —- making it critical to clearly communicate any upcoming changes to your user base. Additionally, it’s important to always include the version number in the endpoint URL so that users know when they’re using an older version.

Documentation is a core component of the overall user experience. Users of your API should be able to depend on accurate and timely information that’s readily available on your knowledge base. Be sure that your documentation includes endpoint use cases and examples — ideally in multiple programming languages — as well as an exhaustive list of error messages.

This tenant of software development and user interface design proposes that systems should behave in a way that users expect. As you develop your API, it’s crucial to put yourself in the user’s shoes and walk through the process they will experience. The results of every action they take should feel natural and intuitive, and there shouldn’t be a steep learning curve.

A breaking change is any change that causes the API to stop functioning. Of course, this is highly detrimental to your clients’ experience as it affects the work they’ve already completed.

To prevent breaking changes from occurring, you’ll want to solidify your API layer, maintain close attention to detail, and never rush any releases. Changes should be made carefully, and they should be thoroughly examined before going live.

If your internal system and hierarchy are exposed, updates could break your clients’ work. Keeping your internal structure under wraps will grant you more freedom to make changes without disruption, as your users won’t be tapping into the inner workings of your API.

With constant enhancements and updates, software is volatile by nature. Limiting exposure to your internal structure will shield users from this volatility.

Ideally, it should only take one request for users to get all the data they need. Your API should be able to give precise, narrow results that answer customers’ needs on the first attempt. In order to optimize results, become familiar with your customer’s needs. Keep in mind the Principle of Least Astonishment and craft a convenient, intuitive experience that requires minimal effort on the part of the user.

Developers who code against API platforms, assisted by the public developer documentation, have come to expect a set of standard patterns in how platforms report exceptional situations. API errors, when not handled properly by the platforms, shift the burden to the developers, which is not ideal. Standard error HTTP error codes such as 400, 401, 403, 500, 502, etc., need to be used with the right exceptional context for which they are intended. Standard HTTP error codes must be accompanied by intuitive error messages suggestive enough for the API callers to understand the situation while not revealing any internal information that helps attackers to exploit the system. 

A good portion of publicly exposed APIs of any modern platform is about returning data faster to the user. Systems of record (SOR) such as relational databases often require heavy queries adding latencies in the API path. To avoid this latency, platforms need to introduce a caching layer between the API and the SOR. Caching systems such as Memcache or Redis are designed to return cached data at extremely low latencies, which will add a better user experience for API callers. When adding a caching layer is not possible for architectural reasons, platforms must rely on fetching the data from read-only replicas of SOR for performance reasons. In this situation, the platform may have opted for a trade-off of faster data over consistency, and if so, it must be clearly documented.

The competition for API monetization is fierce. In your quest to build an outstanding API, remember that users want convenience. Bells and whistles may attract customers, but a dependable, error-free architecture turns them into loyal clients.