Over the years, I have been really blessed to work on a number of API developments and to be able to consume a lot of APIs as well whether the APIs were in finance, sales automation (salesforce), or other services. A lot of the APIs had really noticeable deficiencies which I feel really made using the API a lot more difficult than it had to be.

This blog article is really a look at years of experience with APIs and a first attempt to at trying to make them easier to use for the developer. It’s really important to take time upfront and design a great API because it has the potential to be a huge asset for the company, and also has the potential to also be the company’s greatest liability.

A public API will have to remain virtually the same basically forever, so you really only have one chance to get it right. This is because customers or other integrators typically won’t ever update. If your API doesn’t have versioning you’ll basically never be able to make breaking changes. As users use your API and as feedback is collected you should be evolving the API.

Designing a great API will make complicated tasks feel a lot easier and will reduce a lot of development pain that users will feel. Designing a bad API is easy and will result in a lot of support calls or support tickets.

Characteristics of a Good API

A well constructed and designed API will have a lot of these characteristics:

• Easy to learn & use: even if the documentation is missing.
• Hard to misuse
• Code that uses the API is easy to maintain and read.

I find the best APIs implement the RESTful constraints (see blog article What are REST Constraints for more details about them).

Know The Users

I’ve always believe the biggest problem developers face when designing  anything is that they don’t understand the users.

Typically when you build solutions for users, you are designing for end users that are not normally all that technical. Sometimes, these end users will know what they want the user interface to do but often they don’t.

The problem with API programmers is that they don’t always understand the usecases or workflows that will be required and how users will use it.

Consistent Naming

I consider variable names, and field names to be the most important part of designing a good API. If the names are really poorly named how to use the system will be really difficult to understand and use.

Stripe won against many of the older payment gateways because their API was really well designed and really easily to implement. A big part of this was because it was really consistent.

When I think of consistency, I think of using the same word or concept a lot and always trying to use it the same way. I believe that you need to decide the convention is plural or singular.

My personal preference is that every resource should be plural and ideally be fairly closely named to what’s in the database. The reason I’ve chosen this side of the holy war is because I believe it just makes it easier to know what endpoint I should call regardless of the HTTP method.

Every resource should be a noun instead of an adjective or action word. If the API is well designed you shouldn’t need to use verbs or action words to denote that you’re modifying things.

Helpful Feedback When Errors Occur

User input validation should happen as soon as possible, ideally before you are even trying to look up a record in the database or trying to save.

Your error messages should really be targeted to what the problem is, and probably have a common problems page in the docs. The best error messages tell the developer that’s calling the API what happened, when it happened, what was expected, and how they can fix it. Messages should be really informative and actionable.

Follow Conventions

When designing an API it’s really important to have standard naming conventions. There’s a lot of developers that don’t speak or write English as their first language, so it’s really important to try and use simple, consistent and small words when naming resources and methods.

I like to try and follow the following conventions:

• When possible use the regular standard term, although common short forms or acronyms can be used.
• American English instead of British English, so color instead of colour.
• The exact same name for the same concept regardless of the endpoint.
• Try to avoid standard reserved words (break, case, char, const, int, return, etc)
• Every resource in an API should have a URI that makes sense and can acqurately describe it. So, Company Users should be /employees or /companies/:CompanyId/users

Call Your API Regularly

One of the most important concepts I’ve learned since I started working for startups is that it’s really important to “eat your own dogfood” which means using your product or API regularly.

By using your own API regularly you’ll really start to see all of the little issues and bugs that exist in the design and implementation.

Do you have tips or suggestions that you thought I missed for Designing RESTful APIs?