Gain insights into designing robust APIs, explore essential tools for design, documentation, testing, and deployment. Delve into ALPS, OpenAPI, Postman, and Heroku for comprehensive API development.

Design and Build Great Web API's by The Pragmatic Programmer-01.png

webapis.tar.gz

Testing APIs

Testing API Exercise

Building API Exercise

Building API Exercise Solution

Securing API Exercise

Securing API Exercise Solution

MockAPI

Account Mock API

Company service Mock API

Challenge-1 Mock API Solution

Postman Mock API

At the start of this course, you’ll be introduced to a handful of important practices and principles for designing and building APIs that are robust, reliable, and resilient. You’ll also acquire skills in a wide range of developer tools, including tools for design, documentation, building, testing, security, and deployment. 

You'll learn the best practices for modeling an APIs lifecycle using Donald Norman’s action lifecycle. Then, you’ll learn how to use the sequence diagram for designing APIs and describing them using ALPS. For sketching an API, you will learn about Gehry's sketches. You will also cover OpenAPI and SwaggerHub for API mocking. Moreover, the usage of DARRT and NodeJS will be covered for building APIs. You'll finish with learning how to use the Postman for testing APIs and then deploy them using Heroku.

By the end of this course, you will have an in-depth understanding of how to make fully functional efficient APIs from its inception to its deployment.

Design and Build Great Web APIs

# API documentation

No matter how well we design our API, both server developers and API client developers need some level of documentation in order to understand and use our API. And OpenAPI Specification has some really nice support for generating simple documentation.

API documentation is very much along the lines of technical documentation—it only includes the set of endpoints and associated parameters, request bodies, response bodies, and schemas we included in our document. There is no extended prose covering why someone might want to use our API—nothing like a how-to guide or list of common problems. But basic technical docs are a good start.

# SwaggerHub’s generated documentation
We can use SwaggerHub to generate standalone HTML documentation in a couple quick easy steps. The “Export” menu in the SwaggerHub Editor gives us three options. We’ll see them here:
- Dynamic HTML: This is a Node.js website we can host that renders the documentation in a fairly simple layout. It might make a nice starter site for our API.
- HTML: This is a static site that lists all the operations and has a very simple layout. It’s a single, standalone page. There’s no need to host a Node.js site.
- HTML2: This is also a static site, but it has the added feature of showing API calling examples in a number of languages (curl, Java, Objective-C, JavaScript, C#, PHP, Perl, and Python).

# External API documentation tools

Many other tools and services can render our OAS documents. One of them is known as ReDocly, which currently offers an open-source GitHub repository where we can download the code and read through examples. The company behind ReDocly is also planning to launch an online hosted version (https://redoc.ly) of this service in the future.

The best thing about ReDocly is that we can use the HTML template page that relies on its hosted JavaScript library to render a very nice HTTP API documentation site very easily. All we need is the ReDocly HTML template and a URL that holds the OAS document. For this course, the following file is the copy of the prototype OAS definition file. We can place it in our public GitHub repository and then update a copy of the ReDocly HTML page to point to that file, and then we’ll have a fully working set of API documentation. See the following screenshot:


Learn how to generate API documentation using SwaggerHub and ReDocly.

Introduction

Understanding HTTP, REST, and APIs

Modeling APIs

Designing APIs

Describing APIs

Sketching APIs

Prototyping APIs

Building APIs

Testing APIs

Securing APIs

Deploying APIs

Modifying APIs

Some Parting Thoughts

Appendixes

Generating API Documentation

API documentation