Best Practices for Building with External APIs

A presentation at Momentum Dev Con in October 2021 in Cincinnati, OH, USA by Ben Greenberg

@rabbigreenberg Becoming an API Explorer

Welcome to API Explorer Academy! 🚀 Our Mission ● Discovering what to look for ● Equipping with the right tools ● Loving the journey, even with the bumps along the way! @rabbigreenberg

Before we start, who is this person talking to me? ● Professional API Wrangler (i.e. Developer Advocate) at Orbit ● Ruby is my happy language ● SAN 🛫 JFK 🛫 TLV 🌍 orbit.love @rabbigreenberg 📧 ben@orbit.love

Bonus Slide! We’re hiring 🙌 ● Globally distributed team ● Remote first ● Empathetic product-driven engineering ● Enjoys space puns… sometimes 👉 orbit.love/careers

First of all… What is an API? @rabbigreenberg

“… when a company offers an API to their customers, it just means that they’ve built a set of dedicated URLs that return pure data responses — meaning the responses won’t contain the kind of presentational overhead that you would expect in a graphical user interface like a website.” - What is an API in Plain English @rabbigreenberg

Examples of APIs ● Cat Facts - https://alexwohlbruck.github.io/cat-facts/ ● Harvard Art Museums - https://github.com/harvardartmuseums/api-docs ● Google Books - https://developers.google.com/books/ ● Charity Search - http://charityapi.orghunter.com/ ● National Bank of Poland - http://api.nbp.pl/en.html ● U.S. Street Address Validation - https://www.smartystreets.com/docs/cloud/us-street-api ● Associated Press - https://developer.ap.org/ @rabbigreenberg

You’re interested in an API? @rabbigreenberg

API Explorer Academy: Stage I Initial Discovery

Your Investigation Checklist ✅ 🚀 🚀 🚀 🚀 🚀 🚀 API Reference Documentation Credentialing Rate Limits Pagination Support @rabbigreenberg

API Reference Why do you need an API reference? @rabbigreenberg

“The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.” - OpenAPI Introduction @rabbigreenberg

What are the parameters? What does an error look like? What does success look like? @rabbigreenberg

☑ Does it have an API reference? @rabbigreenberg

Documentation Is there documentation? @rabbigreenberg

Can an API even be used without documentation… ? - Stoplight

Types of Documentation 📚 📚 📚 📚 📚 Overviews Tutorials Quickstarts Code Snippets Use Cases @rabbigreenberg

Describe each status code Soliciting feedback Attributes with data types Describe error types @rabbigreenberg

☑ Does it have documentation? @rabbigreenberg

Credentials Is it secure? @rabbigreenberg

Authentication is Identity Authorization is Access @rabbigreenberg

API 🔑 “I am who I say I am, please give me what I am asking for.” 🔓 “I believe you are who you say you are, here is your data.” APPLICATION @rabbigreenberg

Authentication Protocols 🔐 Basic Auth 🔐 API Key 🔐 OAuth @rabbigreenberg

Authentication Protocols 🔐 Basic Auth ○ Base64 encoded username and password 🔐 API Key ○ A key that identifies an authorized application 🔐 OAuth ○ User scoped authentication ○ Multi-step process @rabbigreenberg

Basic Authentication Example @rabbigreenberg

OAuth 2.0 Client Credentials Flow 1 CLIENT Send Client ID and secret to /token 4 2 Validate client ID and secret Request data with token 3 Send token to client API @rabbigreenberg

☑ How does it authenticate? @rabbigreenberg

Rate Limiting and Pagination Are there limits? @rabbigreenberg

Rate Limiting is about requests Pagination is about records @rabbigreenberg

API Explorer Academy:Stage II Pre-Flight Checks

Let’s check out this API! @rabbigreenberg

Experimenting with an API @rabbigreenberg

Why do we experiment? ✅ See Live Data ✅ Check Assumptions ✅ Do Something Wrong @rabbigreenberg

Save requests to replay later Examine the API response @rabbigreenberg Define parameters, authentication, headers and more

Authorization options: ● ● API Key OAuth Possible API responses: ● ● 200 401 @rabbigreenberg

API Explorer Academy: Stage III Ready to Launch

You don’t have to do it alone @rabbigreenberg

Tools To Help You On Launch Day ✅ SDKs ✅ Low-Code/No-Code Tools @rabbigreenberg

“SDK stands for software development kit. Also known as a devkit, the SDK is a set of software-building tools for a specific platform, including the building blocks, debuggers and, often, a framework or group of code libraries such as a set of routines specific to an operating system (OS).” IBM Introduction to SDKs @rabbigreenberg

Stop worrying about the API @rabbigreenberg

Manages authentication Handles rate limiting and pagination @rabbigreenberg

APIs Can Introduce Breaking Changes Don’t Let Them Break You @rabbigreenberg

Adding Activities to Orbit via the API directly You need to know: ● Headers ● Authentication ● Data format (JSON) ● Data types All these are subject to change (often)! @rabbigreenberg

Adding Activities to Orbit via the SDK You need to know: ● ● What your data is What method to call @rabbigreenberg

● ● ● ● ● ● @rabbigreenberg Build workflows graphically Integrate with numerous services automatically Customer support Build workflows graphically Add custom code solutions More programmer-oriented

API Explorer Academy: Stage IV Creating Outposts

Celebrate your wins along the way @rabbigreenberg

Each new learning is another new outpost in your growth @rabbigreenberg

“Instead of specializing in speedometers or steering wheels, software supply chain companies deliver reusable chunks of code that developers bring together to make finished applications… @rabbigreenberg

… This shift to component software is the next big leap in the evolution of the software industry.” - Jeff Lawson @rabbigreenberg

Stay in Touch ben@orbit.love @rabbigreenberg @bencgreenberg @rabbigreenberg

Ben Greenberg
@benhayehudi

1 / 64

Modern software development nowadays is often focused on the connecting of existing services together to produce something new and useful. Working with external APIs is not for the faint of heart. Whether it is navigating documentation, deciphering obscure API error messages, composing authentication credentials, or more, there are countless potential problem areas to overcome when working with APIs. Creating applications that depend on external APIs should not have to be a painful experience. In our time together, we will uncover several best practices that can make your work more productive, less painful, and more enjoyable.

Best Practices for Building with External APIs

Link for this presentation:

HTML code for embedding:

Share on social media: