January 12, 2022

Getting Started With APIs

Welcome to the API Guide. The purpose of the API Guide is to provide tutorials and best practices for developers creating and working with APIs.

What is an API?

API stands for Application Programming Interface. It is basically how different machines and software talk to each other to create ever more complex applications. Even though APIs can simply refer to an interface to a local library, or the libraries themselves. For purposes of this website, APIs are assumed to be over the network to connect clients and servers (or multiple servers depending on your architecture and terminology).

Why build APIs?

These days, very few applications are stand alone. If you build a mobile app, most likely you’ll need a build a server to provide resources for that mobile app. You’ll have to build internal APIs. And you’ll consume many third party APIs to avoid reinventing the wheel.

However, once you build an application that gains popularity, other developers and companies may also want to interface with it and leverage the technology or data. This can create a great opportunity to exponentially expand the influence of your company/organization. Your API is no longer just a tool to power your mobile app, but a product and a platform in it’s own right.

An API can act as a platform for new partnership opportunities, new revenue channels, or even new features for your organization. Many call this the API economy.

As thousands of developers integrate and work with your API, it may turn into your most valuable asset such as large companies like SalesForce and Expedia. In fact, Salesforce generates 50% of its revenue through their APIs, and Expedia generates over 90% of its revenue through their APIs. Today, billion-dollar companies like Stripe and Twilio has API products at its core.

Different Types of APIs

RESTful APIs over HTTP with JSON is the most popular type of APIs. However, there are other upcoming types such as GraphQL, which is becoming popular especially with applications with many data entities.

What makes Good APIs?

Key things are:

Easy to learn
Easy to use
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to Extend
Appropriate to the audience

Core Principles of RESTful API

RESTful stands for Re presentational S tate T ransfer. Read the history here.

Below are the key constraints, and they can be somewhat abstract. Please see API Design Patterns for more specific best practices for RESTful to see how these constraints are applied.

Client-Server Architecture

Basically, the key to this is separation of concerns. Separate the user interfaces (usually the responsibility of the client) from the data storage and business logic.

Separation of Concerns is a fundamental software engineering principle also - it is also a general principal for software design that isn’t unique to RESTful.
Understanding separation of concerns

Statelessness

Of course, applications are stateful, the server (having a database) is of course stateful. The statelessness refers to that the sever do not store any client context between each request. Each request from the client will have all the information necessarily for the server to provide the response. This is essential when you have higher traffic. Read below articles to understand why.

Cachability

This principle naturally follows Stateless. If each request is stateless and have all the information necessary information for the server to produce a result, then theoretically result can be cached. The response needs to define if a data is cacheable or not. Of course, if you can cache the result, you save back and forth with the Server, thus again help you scale.

Layered System

This just means that client does not need (and should not) to know if it is directly connected to the server or someone other layer. Again, this allows you to have proxies and load balancers.

Uniform Interface

This is probably the most core constraints for RESTful. It simplifies the architecture.

Resource-Based

Individual resources are identified in requests using URIs as resource identifiers. The resources themselves are conceptually separate from the representations that are returned to the client.

Basically, this dictates how the URI schemes should be designed. We’ll touch on this principle in more detail in design patterns section.
Manipulation of Resources Through Representations

When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource on the server, provided it has permission to do so.

This constraints how we design the schema for data returned from the sever. Design patterns section will have more articles on how this is applied in practice.
Self-descriptive Messages

Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type (previously known as a MIME type). Responses also explicitly indicate their cache-ability.

Basically, even though RESTful doesn’t dictate the payload schema (it can be JSON or XML), but whatever format you chose, client should be able to know the format type.
Hypermedia as the Engine of Application State (HATEOAS)

A hypermedia-driven site provides information to navigate the site’s REST interfaces dynamically by including hypermedia links with the responses.
- Understanding HATEOAS
- Is HATEOAS right for you? - this rule is often get broke most.

Code on Demand(optional)

Sever can let client download code to execute. This usually make most sense in the Browser. The issue is that this reduces visibility, so it is used less often.

What is Code on Demand

Difference Languages

You can virtually develop your APIs in any language. We have lists for language specific tutorial, api-guide and libraries. However, it is worth a while to go over rest of the api-guide as many of the principals are language agnostic.

Terminology:

The terms we use on this website, as some can be ambiguous.

API: for the purpose of this website, these are remote APIs, i.e. APIs delivered over the network. Often times, it refers to RESTful APIs over HTTP with JSON, as it is most common.
Library: a collection of non-volatile resources (usually specific to a computer language) that is used to develop more complex software in that language.
Client: The software that are consumers of the APIs.
Services: This refers to the the software that resides on the servers that provides the API to the services.
Server: This refers to the physical machines.
API Provider: the company or organization that provides a set of API for other developers.

Get Insights Into How Customers Use Your Platform 14 day free trial. No credit card required. Learn More