eCommerce Tips & Trends

5 tips for API success

David Garvey

by David Garvey

On 2018 M04 3

by David Garvey

In today’s digital economy, APIs play a vital role in allowing businesses and the services they create to interact with each other, building on each other’s expertise to create systems and solutions which are greater than the sum of their parts.

By using APIs, a business can unlock value in internal systems, drive growth and encourage innovation and integration.

But it’s not enough to simply create an API, sit back and expect it to be successful.

There’s much more to it than that, you need to have a strategy which will help you create an API which meets both your needs and that of your consumers.

With this in mind, here are 5 tips for API success.

1. Mix predictable design with practical design

This first one is about making your API easy to use.

By designing your API in a predictable way, with consistency in your URL’s path structure, parameters and data objects, you will reduce friction for developers who want to use your API.

Two common approaches are:

  • REST: A resource-based approach where endpoints are designed around an object or resource. For example, a product on an e-commerce website would be accessible through a /product endpoint.
  • RPC: An operation-based approach where endpoints are designed to around a task or operation. For example, to apply a discount on an e-commerce website you would call the /applydiscount endpoint.

RESTful APIs are very predictable thanks to their strict conventions on path structure and the use of HTTP methods to allow the same path to be used for several purposes.

However, as clean as REST is, sometimes it makes sense to provide shortcuts for developers.

By using RPC-style paths, to encapsulate the functionality of several RESTful API calls into a single API call, you can make a developer’s life easier.

For example, let’s say you have an e-commerce API which has resource-based /order and /shipping endpoints which have to be called separately to complete an order.

Rather than having the user call the two endpoints separately you could have an operation-based endpoint, /completeOrder, which would be able to accomplish the same result but with a single API call.

The best APIs will combine both predictable and practical approaches to give the best developer experience.

2. Ensure your API is performant

Performance is an important aspect for APIs and a common non-functional requirement.

The overall performance of the API can be affected by many of the upstream components such as databases, APIs and other network services, and any latency added by these components is felt by end users.

The performance of your API will therefore depend on the nature of the requests and the data sources on which your API relies.

There are several ways you can mitigate this latency issue:

  • Optimise your database access: Slow database access can greatly hamper an APIs ability to respond quickly, so by speeding up database queries you can drastically improve your API response times. One approach is to use in-memory databases, such as Redis, which provide quicker response times by virtue of holding all their data in RAM. Another approach is to ensure that your databases are optimised by implementing appropriate indexes which are tailored to meet the needs to typical queries. Finally, precompile aggregated data so that it can be easily referenced when needed, rather than calculated on demand.
  • Implement caching: Optimising database access is good, but removing the need to access your database is even better. If you are able to provide cached responses directly instead of having to query a database you can remove a significant part of your server-side processing time.
    By implementing a caching layer for ‘safe’ requests, such as GET requests which generate HTTP 200 status codes, responses can be copied from a cache rather than having to be calculated by the API server. This also has the benefit of increasing the number of concurrent requests that your API is able to deal with when compared to a non-cached implementation, because your server can respond quicker, it can free up resources which would have otherwise been consumed.
  • Think geographically: The location of your servers plays a part in improving performance. Servers located a long distance from consumers, or in regions with poor communication networks, will add latency to requests. By geographically locating servers close to key consumer markets you will reduce the amount of network latency experienced by your API consumers.
  • Target poorly performing endpoints: Make informed decisions on which of your API endpoints are the best candidates for optimisation by reviewing your API analytics. Pay attention to metrics such as server-side processing time and overall request latency, which are very useful for this purpose.

3. Provide meaningful feedback in responses

By providing meaningful feedback in responses you can eliminate some of the guesswork involved when a developer is trying to debug an issue.

Good feedback comes in both the form of an HTTP status code and also an error message. By using the correct status code you are making it very clear what type of problem occurred, for example a 401 lets the developer know they make an unauthorised request.

However, you can improve this further by also including an error message in the response body informing them why the 401 occurred. You could also provide links to relevant documentation as part of your message.

By doing this, not only will you will make developers’ lives easier and less frustrating, but you will also reduce the number of support issues you need to deal with.

4. Provide useful documentation and examples

Without documentation, your API consumers will struggle to understand how your API works. You should provide documentation which covers all the endpoints which are available, with each endpoint being described by its inputs and outputs.

Your documentation should include:

  • General description: Can be useful to prevent any ambiguity, if it’s not already obvious from the path.
  • HTTP method: Using POST, GET, PUT, DELETE etc. helps separate endpoints which have the same path.
  • Path: The path for the endpoint.
  • Input parameters: For each input parameter, include the name, type, location (path, header, body), description and whether they are mandatory. Include example data schemas for objects.
  • Responses: Show the possible responses returned by the endpoint, including the HTTP response code and any data represented as schemas.

Consider whether your endpoints need further clarification through working examples. These can give context to complex scenarios and allow consumers to understand how a set of endpoints can work together.

They also work well for getting consumers started, so that they have a good understand of the basics before moving onto more complex topics.

For a good illustration of how to structure API documentation you can refer to the OpenAPI Initiative specification, which has an example implementation under the guise of a pet store API.

By following a specification such as this you are opening up opportunities for your API to be easily imported into other tools and systems.

To make consumers’ lives easier you may also want to consider providing API toolkits or code generators in a number of different languages.

However, you will want to have a streamlined, automated process for generating these so it’s easy to keep them updated when you release new versions of your API.

5. Listen for feedback

By supporting and listening to feedback from your community you can learn a lot about your API. Your users can be a great source of ideas and will let you know of any issue or frustrations that they are facing.

Acting on information provided by the community you can improve your API in many ways. Look for trends and pain points which you can easily address. Users like to know they are being listened to, so you may find that by doing so you create strong advocates for your API.

About the author: David Garvey is the APAC Technical Director for, an open-source API Gateway. He recently helped judge Easyship’s eCommerce Hackathon.