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

# Sketching the Onboarding API

Like the pencil sketches Gehry uses to explore possible building designs, we can create API sketches to explore our API designs. For example, in the Onboarding API project we’ve been working on over the past several chapters, we have the `startOnboarding` action defined in our ALPS document when we added action elements. Let’s walk through a sample design sprint for just this one element of our API.

For starters, our ALPS document includes the following element that describes the `startOnboarding` action:
```xml
...
{"id" : "startOnboarding", "type" : "unsafe", "rt" : "wip"}
...
```
Now, we need to turn that into an actual message that would be sent from the API provider to an API client application. One possible API response might look like this:
```xml
{
"startOnboarding" : "http://api.example.org/start"
}
```
From this example, we simply translated the `startOnboarding` action in the ALPS document into a name-value pair in a JSON message. That certainly works. But as we look at it, quite a bit of information is missing (or assumed). Maybe we should add a bit more content to the message to make it easier to understand.

Here’s the next sketch for the `startOnboarding` action:

```xml
{
  "link" : {"id" : "startOnboarding", "href" : "http://api.example.org/start"}
}
```

This is a bit easier to read and understand. We created a link element in the message that contains the `id` element from the ALPS document and created an `href` element to identify the actual URL.

Again, as we look at this sketch, it might occur to us that our response messages are likely to have several `link` elements in them. Maybe this sketch is better:

```xml
{
  "links" : [
    {"id" : "startOnboarding", "href" : "http://api.example.org/start"} 
  ]
}
```

Now we have an array of links, each with their own `id` and `href` values.

Something else that is missing from this message is some indication of its type—what kind of message is this response? For that, we’d like to add another named element at the root of the response, which looks like this:

```xml
{
  "onboarding" : {
    "links" : [
      {"id" : "startOnboarding", "href" : "http://api.example.org/start"}
    ] 
  }
}
```

It’s clear that this is an onboarding message. That can come in handy for API consumer applications that need to know what type of response message they have in order to know how to parse the incoming data and/or render it on a screen.

How about we jump ahead a bit? The following design actually looks close to the final design to use for the Onboarding API:



Learn how to sketch an API using the example of the Onboarding API.


API Sketching Example

Learn how to sketch an API using the example of the Onboarding API.

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 Sketching Example

Sketching the Onboarding API