A Pragmatic approach to API design – Lessons from building our API platform

September 8, 2017

(Note: Our v2 APIs are now available in production as of Nov 5, 2017)

Our version 1 API set was launched 4 years ago and since then we have learned quite a bit on designing, sustaining and supporting these APIs for our growing developer community and eco system. We want to share our experience and also what our v2 APIs looks like. We have covered the API authentication in a previous blog and so we will stick with some practical design principles in this blog.

Your APIs have a longer life - do it right the first time

When we launched our first version, we thought that we can release a basic version and keep enhancing it and making it better every release. This holds true in general but once your developers start using the APIs, you cannot afford to break backward compatibility by making fundamental changes to the resource names, formats you accept, return codes or the implementation logic around the APIs that can affect the intended outcomes.

  • Separate your APIs into logical grouping of resources – in our case, its users, meetings, accounts, reports etc.

 

  • Follow the rules of Idempotency when implementing the APIs - in summary, all operations with the exception of POST should be idempotent. Idempotent APIs should be safely repeatable with the same outcomes from an application using your APIs

 

  • Define your endpoints clearly and decide what actions (CRUD) apply to them. All endpoint names should be nouns (not verbs). For instance, in order to create a new user, you will use “POST https://api.zoom.us/v2/users” (and not "https://api.zoom.us/v2/users/create")

 

  • If the API doesn’t fit exactly into the CRUD semantics, define the action to make it appear as a field in the resource. For instance, if we are going to expose joining a meeting as an endpoint, we will create “POST https://api.zoom.us/v2/users/{user id}/meetings” but with the following body

{

"method": "join",

"params": {

"meeting_number": 2011000232

}

}

 

  • PUT vs PATCH – regardless of the debates and what you read, follow the spec. When you are making partial updates to a resource, you should follow RFC 5789 and use PATCH method. If you are making a full update, then use PUT. Most of the updates are partial in our case and so PATCH will be more frequently used in our v2 APIs

 

  • Limit which fields are returned back by your platform – Your developers are not going to need the full state of the resource every time. Expose an option in the API to get specific fields. For instance, GET “ https:://api.zoom.us/v2/users/{id}?params=email, pmi” will return only the user’s e-mail and pmi and not the whole user data

 

  • It would be ideal if the create/update APIs return the entire resource representation instead of just the timestamps and status. A number of apps might need to locally store the current resource representation and this will help eliminate making another API call to get the updated resource details

 

API documentation

Most of our developers check out the documentation first before they decide to put engineering efforts to do any sort of integration with our platform. Your APIs are only as good as your documentation. Your API doc should be publicly accessible and browsable. We have recently moved all our API documentation to GitHub

Add a playground

A playground is an essential element of your API platform and helps your developers get familiar with your APIs. We have replaced our existing playground with swagger and adapted the OpenAPI spec.

Support OpenAPI specification

This is an effort to standardize the API descriptions using Swagger and helps developers and API testers tremendously.  Your developers can take your OpenAPI spec and just use it with any standard REST clients or create new libraries instantly.

We now support OpenAPI spec for our APIs. Check out our recent blog by Zoom Developer Advocate Joshua Woodward.  Zoom APIs are now described in a consistent and well-known specification format.

Versioning Schemes and Versioning Policy

An API represents a contract between the platform and the developers. In order to smoothen the effort it takes to migrate the apps that use your APIs, define a versioning policy for your APIs. A versioning policy allows us to roll new versions of the API while giving enough time for the developers to migrate. We are now rolling out version 2 and our version 1 will continue to be supported for 24 months. While we will continue to fix bugs on version 1, all new APIs will only be available on version 2. This is a balance between the engineering cost of sustaining older versions of API and developer experience.

There are different approaches to versioning schemes. A common model that we have adapted is to add the API version in the requests. API versioning is a topic that is worth discussing in a separate blog post and we will put that out soon.

We are excited and look forward to release our API version 2 soon. Please do respond with your comments and suggestions -  we will continue to make Zoom a collaboration platform of choice to build your apps.

Thiya Ramalingam
Thiya heads the platforms, integrations, product partnerships and private cloud engineering @ Zoom