In this module, you'll learn about designing Application Programming Interfaces (APIs). We'll cover specific tools and processes for documenting APIs, teach you best practices for the APIs you design, and demonstrate how to design an API based on user stories.
Often when developing applications, you want to expose functionality for other developers and teams to use. For these situations, you develop an Application Programming Interface (API). An API defines how a client (the code that needs the exposed functionality) interacts with a server (the code that exposes the functionality). At Amazon, this will most often mean designing RESTful services (recall HTTP REST operators from Unit 4). When defining a RESTful API, you will decide which resources a client can access and which HTTP methods can be used.
You create an API by:
You define and document an interface by describing each operation you will expose, along with its input, outputs, and errors. Other developers use the definition to write clients that use your service. This is the same benefit we get from writing interfaces in our Java code.
Remember, we often design and expose APIs to other teams, either internally or externally. This means that having a clear, well-documented API is extremely important! This will help your clients on-board quickly and correctly.
When documenting an API, you could write a wordy text document that describes the interface. However, English is ambiguous. Mistakes are often made documenting the interface or in how a developer interprets what is written in the document. To prevent these types of errors, we use an API definition language to capture the details of the API. The unambiguous, standardized format of an API definition language is both human and machine-readable and enables tools that can:
There are many types of API definition languages. Some are independent of implementation details such as language; others are very implementation-specific.
In this module, we'll learn how to create API documentation using RapiDoc. RapiDoc uses OpenAPI, a popular set of rules for structuring API documentation. Using a standard set of rules like OpenAPI has many advantages, one of which is that our API pages will look and feel like other API pages, making them more usable by everyone.
To create a RapiDoc, you'll want to first make an index.html file on your machine. Here's a basic structure for getting started:
<!doctype html> <!-- Important: must specify -->
<html>
<head>
<meta charset="utf-8"> <!-- Important: rapi-doc uses utf8 characters -->
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
</head>
<body>
<rapi-doc
spec-url = "https://example.com/api.json"
>
</rapi-doc>
</body>
</html>The JSON file for your API definition might look something like this:
{
"openapi": "3.0.0",
"info": {
"title": "Sample API",
"description": "Optional multiline or single-line description in CommonMark or HTML.",
"version": "0.1.9"
},
"servers": [
{
"url": "http://api.example.com/v1",
"description": "Production server"
},
{
"url": "http://staging-api.example.com",
"description": "Staging server for testing"
}
],
"paths": {
"/users": {
"get": {
"summary": "Returns a list of users.",
"description": "Optional extended description in CommonMark or HTML.",
"responses": {
"200": {
"description": "A JSON array of user names",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
}
}
}Learn about the fundamentals of API design, RESTful services, and why proper API documentation is crucial.
Learn about data serialization formats and tools used for API documentation.
Learn best practices for designing APIs that are clear, consistent, and future-proof.
Learn how to translate user stories and requirements into API designs.
In the guided project for this module, you'll apply what you've learned about API design to start designing the API for your Learn and Be Curious project.
This project will guide you through designing an API for a subscription service, where users can subscribe to receive products on a recurring basis.
Begin working on the problem statement section of your design document, which will define what your project aims to solve.
The official OpenAPI Specification documentation.
Examples of API documentation created with RapiDoc.
A guide to best practices for designing RESTful APIs.