API Design and Development Best Practices
mm
Leo Farias
Posted on: May 10, 2018
Development
Tags: API design development http
Tags: API design development http

Application Programming Interfaces, or API, offer a set level of access to a company’s digital resources. Other software can leverage these API to create an expanded range of services for mutual customers which benefits both companies.

User experience is key for modern companies. A big part of providing better experience is offering ways for customer-facing software to interact with other popular services: social media, analytics programs, mobile wallets, and more.

API are most valuable when they’re widely adopted. It’s important to build something functional and elegant that makes it simple for other developers to use it. With that in mind, here are some best practices for creating secure, effective, popular API.

Always Use Versioning

Never change a published API. Changing the structure could disrupt software created by API consumers, which can lead to anything from reputation damage to pricey liability claims.

Instead, label every version sequentially to provide a clear signal of which is most recent. Incorporate versioning into URLs (for example, http://concepta.com/v4/projects).

Always provide plenty of notice when stopping support for old versions to allow developers time to update their software.

There’s no downside to versioning. It’s free and easy to do, so there’s no real reason to skip this step even if the API isn’t intended for public release.

Secure Your Endpoints

Endpoints are the only access points to the outside world, making them major vulnerabilities. At the same time they must be accessible, since the point of API is for other organizations to access a company’s resources.

To resolve this dilemma, focus on securing endpoints against unauthorized intrusion using authentication. There are three primary options:

  • Basic Authentication: Authentication is provided using a base64 encoded string.
  • Token-based authentication: The user signs in with a username and password, then receives a token for authentication to further resources.
  • Hash-based Message Authentication Code (HMAC): Server and client each have a unique cryptographic key. The client uses this key to create a hash with the request data before sending it.

In addition, always apply timestamps to API requests and responses. It’s also a good idea to consider role-based access control to allow tiered access to different levels of users.

Validate Everything

Bad data can throw the entire system off, so don’t automatically accept user input. Run all incoming data through a validation protocol.

The parameters here should be simple yet detailed enough to establish whether the data “looks right”. Some questions to ask:

  • Is it the right number or type of numbers?
  • Is it an acceptable scheme?
  • Are all required request parameters included?

Validation is a basic level of defense that keeps obviously wrong data out of the system.

Use HTTP Correctly

HTTP is a serious asset when it’s used properly. Resist the urge to be “more efficient and precise” by ignoring error handling or using obscure codes.

Two areas to focus on are CRUD operations and response codes.

Common CRUD operations should be used according to common practice:

  • GET- Retrieve a representation of a resource.
  • POST- Create new resources or sub-resources
  • PUT/PATCH- Update existing resources
  • DELETE- Delete existing resources

Response codes provide feedback to help developers understand how to use the API.

  • 2xx Successful operation (OK, Created, Accepted, No Content)
  • 4xx Client-side failure (Bad Request, Unauthorized, Too Many Requests, Request Timeout)
  • 5xx Server-side failure (Bad Gateway, Gateway Timeout, HTTP Version Not Supported)

Favor specific codes when possible. It’s very hard to use an API that only returns general failure or success codes.

Linking to the appropriate section of documentation when returning error codes will make API more user-friendly, too.

Favor Descriptive Nouns For Collections/Resources

Using nouns as opposed to verbs in the URL serves two purposes. First, it keeps the URL simple and easy to read and use.

Second, verbs are used to operate on resources described by the URL. Having them also IN the URL can be confusing.  Notice that POST /postNewAddresses is much less elegant than POST / addresses.

Be descriptive with nouns so users don’t have to play guessing games. The biggest problem here is when developers favor style over efficiency.

Instead of using /photos they use something cute like /memories or /favorites that doesn’t tell users what the resource actually is.

A last note note: it’s common practice to use plural nouns, so do so in the interests of consistency and expected behavior.

Provide Thorough Documentation

Documentation can make or break an API. Provide everything users can conceivably want to know to smooth their development process as much as possible.

Keep info in context since users will very rarely be reading documentation in order.

The best documentation addresses these elements:

  • Index or navigation aid
  • Quickstart guide
  • Authentication
  • HTTP requests
  • Functions of every call in API
  • Each parameter and all of their possible values (types, formatting, rules, whether or not it’s required)
  • Error handling and error codes used (with easily understood explanations to aid in troubleshooting)
  • Tutorials that cover a specific task thoroughly without adding extraneous information
  • Version numbers

Be Consistent and Predictable

The goal is to create an API that’s easy and intuitive to use. Make paths easy to follow and use consistent behavior logic throughout.

Use codes how people will expect, favoring common methods when there’s no pressing reason to change something.

In short, don’t try to reinvent the wheel. Prioritize functionality and simplicity. If the API is too complex it creates a barrier to adoption.

API aren’t only for public use. Private API are a powerful tool for exposing outdated legacy systems to new technology. To learn about how to update your stack using API, schedule a consultation with the experienced developers at Concepta!


Request a Consultation

Leo Farias is the CEO and Co-founder at Concepta. He received his MPS in Business of Art & Design from the Maryland Institute College of Art. With over 18 years of technology-focused experience, he plays a vital role in architecting and leading various mission-critical projects for world-renowned clients like Time Warner Music, Orlando City Soccer, Vasco de Gama and Corinthians Soccer Club.