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

# OpenAPI Specification

Earlier, in the example about creating a toile, we learned that garment makers rely on detailed design documents, called patterns, for directions on how to create the final piece of clothing. It turns out there is a whole world of pattern making. Home patterns (called sloper patterns) are not the same as block patterns, which are used for industrial garment machines. No matter the type of pattern, the process of adjusting or custom-fitting the pattern is called grading. All this pattern work relies on a standardized set of pattern symbols—a language of patterns—that the cutter or sewer needs to understand ahead of time.




This kind of pattern language exists for prototyping APIs too. The main GitHub repository for **OpenAPI Specification (OAS)** describes it as “a standard, programming language-agnostic interface description for REST APIs.” The general goal of OAS is to accurately and comprehensively define an API so that API consumers don’t need access to any other information—just the OAS document—in order to understand and successfully use the API.

# Tam’s API specification
The roots of OAS reach back to Tony Tam’s 2009 project to create a definition language of RESTful APIs. He was working at an online dictionary company called Wordnik at the time. The first published version of what was then called SWAGR (pronounced swagger) was released in 2011. Tam released version 2 of the Swagger Specification in 2014, and the most recent release, version 3, was published in 2018.

OAS isn’t the only API specification format, but it is one of the most widely used formats for RESTful APIs today.


# Defining the API

One of the reasons OAS is good for creating API prototypes is because it’s a rich format for defining the implementation details of APIs. It allows us to outline the URLs our API will publish, along with the inputs API users can send and the outputs those API users can expect to get in return. For example, we can publish all the API details like the language of sewing patterns. OAS is an engineering language that allows us to accurately convert our prototypes into production.

For this reason, we refer to OAS as a definition format. Apiary’s API Blueprint is also an API definition language. In contrast, we used the ALPS document format as our description language. As we saw earlier, ALPS is a good way to describe the API design in general terms, but it isn’t appropriate for actually defining the implementation details of our production API.

While we don’t need to define every single detail of our production API using our prototype, OAS is one of the best formats for expressing those details. That means our prototypes have the potential to be very explicit and, eventually, very accurate. This can eliminate any surprises when moving from the final prototype into production implementation.

> **OAS Versions and Formats:** OAS has been around long enough that more than one version is in use today. We’re using version 3.0.0 in this course. Many organizations and OAS tools also support version 2.0. And both versions support both YAML and JSON serializations of OAS documents. Be sure to check what version your team is using and that it’s compatible with the OAS tools that you’re using.




Learn about Tam's API specifications and how to define an API with it.

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

API Prototyping with OpenAPI

OpenAPI Specification