Jason HarmonAbout the author: Jason heads the API Design team at PayPal, helping development teams design high quality, usable APIs across the platform. He blogs at apiux.com, has a Youtube channel, API Workshop (https://www.youtube.com/channel/UCKK2ir0jqCvfB-kzBGka_Lg), and co-organizes the AustinAPI.com meetup.

Since 2013, PayPal has been developing a new generation of APIs, using REST semantics. While our public API developer community has seen the outward effects of this, internally we’ve been using the same strategy. Since 2013, we’ve defined most of the PayPal platform using REST APIs.

As part of the team guiding this engineering-wide project (we call it PPaaS aka “PayPal as a Service”), our API Design team has had the privilege to work with a huge number of development teams. We consult with development teams on API design to ensure the broadest consistency, sound usability, and a myriad of other concerns.

During the process of collaborating on hundreds of API designs, we’ve developed a detailed set of internal standards. With the size of our team it’s important to provide some level of detail. This provides our developers building APIs clear guidance. However with all the detail we’ve provided, it can get a little tough to get started learning what good API designs look like. In an attempt to capture the basics, and provide an overview of our Standards, we’ve composed our API Style Guide. Rather than keeping this within our internal developer community, we removed any internal or proprietary references, and made it something anybody could use as a set of API design guidelines. A handful of other organizations, such as Heroku and The White House have shared their standards as well.

The hope is that more organizations that are passionate about APIs will share their design guidelines. This can only improve the consistency of the API space. While there are many books on the subject, looking at popular APIs is often the first place new API developers get started. Often this leads to guessing why a design works the way it does. By providing Standards or a Style Guide, new API developers can get a better sense of the rationale behind a functioning design.

We’ve published PayPal’s API Style Guide on Github. Most of the examples provided are based on our REST APIs, which you can find out more about on developer.paypal.com.

Tagged with:
 

Comments are closed.