10 Questions for Great API Design

02 Mar 2016
by: Lou Powell

1) Who is the consuming audience? Is it internal? Customers? Partners? Vendors?

Determining audience will drive new questions. What is their level of understanding of the business process driven by this API? How familiar are they with my company, industry? Answers to these questions will help you determine how much attention will need to be paid to things like documentation, taxonomy, vocabulary, and security.

2) What data will this API surface or collect?

Is there a compliance or legal concern about the data I am collecting or sharing through this service (Corporate sensitive data, PII, PCI, SOX, HIPAA, GLBA)? What approval processes will need to be in place? Should we have agreements in place for how they will treat the data once they take ownership of it? Will I need to be able to hide methods, fields, or groups of records based on the application that is requesting the data or maybe the user or entity that the data is being requested for?

3) In what scenarios will this data be requested or submitted?

You will have to determine the commonly anticipated scenarios in which the data will be used so that you can create methods that are logically aligned with the use cases. There will likely be many contexts to how your data will be consumed. Try to provide simple solutions based on how developers will consume your API, not on the easiest development path for surfacing the data.

4) Do I need to create filters or pagination for service efficiency?

How large is the average payload that you will produce with a given request? What is the largest payload you could produce? Is this payload practical for an HTTP based service? You want your service to be functional and practical. Use pagination to reduce record sets to most commonly used sets. Use filtering parameters to reduce record size. Be mindful not to create so many filter options that it eliminates the value of cache.

5) What service standards do I want to support?

ReST, SOAP, idoc, xml-rpc, json-rpc, etc. Be sure to consider the formats desired by the developers who will consume your services and not just your preferred standard. If you need to support many standards you will definitely want to utilize a gateway product that translates your service into different formats on the fly to keep you from having to manage an unwieldy codebase.

6) What definition formats will you support?

Swagger, WADL, API Blueprint, ioDocs, Schema, WSDL.

SmartBear overview of SOAP and ReST

APIUX: An Overview of REST Metadata Formats

If you are creating an API for an unknown development community, you may need to consider creating and supporting many definition formats. To ease this process you can use tools like MITs Lucybot to convert from one definition to another. This will allow you to utilize one definition format for marshaling the design and development of your services and then converting it to other formats for publication.

7) Are there language localization considerations? 

Will the users of this API expect the data to be presented in a native language other than English? Don't consider whether the current data store has multiple language support. The question is, "is it needed by the API consumers?" And if the answer is yes, then build it into your design. You can always add languages over time. Be sure to keep your developer community updated on what is available on your API portal and through regular email communications.

8) Are there time zone localization considerations?

Will the data that is returned in the payload need to present local dates or times? Is the originating data stored in server local time, contributing device local time, GMT, UTC or maybe a proprietary format? Is Daylight Savings Time a concern?  If so, don't make the consuming developer do all of the work. Simplify the API experience and make it more valuable by centralizing the business rules for presenting data.

9) What error conditions should be considered?

You should be starting with a global set of error conditions that are shared among all of your services. Add specific error conditions as required for your new API. Be thoughtful about how helpful your error messages are for developers that don't know your business or industry well. Make sure your error messages are as fine grained as possible. My preference is that your error message contains an error code, description and suggested resolution. Err on the side of verbose in your descriptions and resolutions for audiences that you do not have direct contact with.  Box.com posted a great article with suggestions on error design.

10) Is this a synchronous or asynchronous service?

Will there be live users waiting on an answer from the service? What is the response expectation? If your API is synchronous, be sure to design it to be as fast as possible. To improve performance you can create separate, optimized data stores, optimize the request structure to be highly cacheable, or utilizing filters to reduce records and attributes returned in the payload.  If you are creating an asynchronous service you will want to be more concerned about time-out and the implications of partial transaction completion that speed of service. Consider utilizing pagination of very large datasets and ensure that your time-out recovery is very cleanly considered and designed. 

This is definitely not a comprehensive list, but it should allow you to answer many of the questions that we see regularly overlooked in API designs.