6 Brilliant Tips from API Design Experts

Ranjan Dailata

Solution Architect at Aezion, Inc. | + posts

Ranjan Dailata is an Aezion Solution Architect and Aezion Labs Lead.

As companies continue to realize the value of APIs, the importance of API design can’t be overstated. Overlooking fundamentals like thorough documentation will only lead to an API that’s difficult to use. Of course, a lot goes into great API design, and these six tips from the experts can put you on the right path.

1. Provide Thorough Documentation

Proper documentation seems so incredibly simple, but this fundamental is often neglected by developers due to the tedious tasks associated with creating and organizing it. Still, you must look at it from the user perspective and remember that, no matter how much you despise creating it, a well-documented API is the only API suited for success.

If you need a new way to view documentation, remember the importance of a first impression. Documentation is often the first thing a potential user looks at when choosing an API, and it’s the materials they’ll continue referring back to should any issues arise. Therefore, great documentation both encourages adoption and helps prevent abandonment, two essential elements of a successful API release.

2. Invest in Stability

If you’ve ever had the pleasure of using Facebook’s API, you’ll know that their hacker culture has them rewriting and releasing mammoth changes every so often. The reason why Facebook can make this work is simple—they have billions of users and a major market share. With that said, Facebook’s approach is less than developer friendly.

At your company, you should seek to keep old versions of your API running for a long time, even when changes need to be made. To achieve this stability, make sure you use appropriate versioning tactics so updates don’t break the API for old-version users.

Additionally, aside from making your API stable for users, try to keep it internally consistent, too. This means using common parameters on a global basis and opting for an architecture that reuses naming conventions from one version to the next.

3. Make Security Standard

The increasing importance of security is something developers can’t ignore, but many either intentionally or unintentionally approach security in a way that’s entirely too difficult for the end user. If you’re providing APIs, you should offer realistic examples of authenticating and authorizing access.

Additionally, you should make sure security is a standard practice, and not some elusive protocol. For instance, the ideal thing is that a user doesn’t have to write any code to ensure security, and if they do, it should take them no more than five minutes.

4. Accommodate Advanced Users

As a developer, it can be extremely difficult to look ahead and predict all the ways users can end up using your API, but it’s your job to try to design it in the most proactive manner possible.

The developers at Phrase share a great, simple lesson in this regard, explaining: “When we first started developing Phrase, we could not imagine the amount of data our customers would want to manage with our platform. This caused problems eventually, since some of the endpoints we offered in our API did not offer pagination. Thus for larger customers they returned hundreds of thousands of records at once.”

As they began to realize the problem, they simply made sure that all results that are returned in list form are paginated automatically. In your API, accommodating advanced users and use cases may look different, but challenge yourself to get in the user’s shoes and think ahead.

5. Control Performance

If you don’t anticipate having a lot of API users initially, you may not even think about performance issues or resource consumption. However, just as you should accommodate future users in other ways, you should safeguard the performance of your API by setting and enforcing limitations.

In addition to ensuring that your servers are never brought down due to insufficient capacity, it also sets good practices for your users by communicating maximum requests in a given interval, throttling behavior and so on. Taking the time to do this will improve performance, even if you’re not starting with thousands of users right out of the gate.

6. Focus on Ease of Adoption

If you’ve followed all these other design tips—especially the first one regarding thorough documentation—you’ll have set yourself up for success with this last one: Removing friction from the adoption process. To ensure your API is easy to adopt, you should identify a few users who are new to your API, and observe the effort required to get it up and running.

Without any help, a user should be able to at least implement your API in a basic manner on their own, aided by a simple walkthrough or tutorial. Generally, 15 minutes or less is a good target.

If you think these insider tips are useful, just wait until you sit down and speak with one of our experts. Contact us today to discuss your API design, integration or custom software project.

This is article 3 of 4 in a four part series on Application Architecture and Systems Integration. You can view the related articles at the links below — or simply click to download our comprehensive Operational Guide to App Architecture & Systems Integration White Paper:

Ranjan Dailata

Solution Architect at Aezion, Inc. | + posts

Ranjan Dailata is an Aezion Solution Architect and Aezion Labs Lead.

Blog