API Management: 11 Best Practices for Developers

By adhering to these best practices, you can craft an API that users love — rather than one that’s cumbersome and prone to breaking.


The proliferation of Application Programming Interfaces (APIs) has made it easier than ever for software platforms to leverage the benefits of third-party applications. These robust protocol infrastructures enable the seamless exchange of data between multiple applications.

Though to gain a competitive edge, APIs must be crafted with the utmost degree of convenience and stability. For businesses that want to successfully monetize an API, you need to ensure that it is truly user-friendly. By adhering to best practices, you can craft an API that users love — rather than one that’s cumbersome and prone to breaking.

Here are 11 best practices to consider as you develop your API:

1Construct the API Semantics Properly

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.

2Always Use Secure Socket Layer (SSL) Protocol

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.

3Provide Support for Filtering, Sorting, and Pagination

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

4Manage Versioning Effectively

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.

5Maintain Up-to-Date API Documentation

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.

6Uphold the Principle of Least Astonishment

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.

7Avoid Breaking Changes

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.

8Prevent Your Internal Structure from Leaking

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.

9Provide Users With the Results They Want

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.

10 Handle Errors Gracefully and Intuitively in API Responses

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. 

11 Improve performance for large queries

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.


Alex Bunardzic is a seasoned leader in the field of applied high technology and currently serves as Senior Engineering Manager for Exact Payments. He has over twenty years of experience leading teams and organizations toward the successful delivery of outstanding technical solutions, and has taught courses at the British Columbia Institute of Technology, Langara College, and Vancouver Community College. Alex has an insatiable appetite for discovering and mastering best-of-breed, leading-edge technologies and strives to apply them immediately to solve challenging business issues.