At its introduction REST wasn’t well understood. The lack of code examples and tools made it difficult to fully realize the concept of REST. The story is very different today. Today developers have access to a wide range of technologies used to design, develop, debug, and interact with web-based APIs.

In this lesson, I’ll introduce you to some useful tools related to REST APIs. There are many software libraries available for creating REST APIs across the spectrum of programming languages. These libraries allow developers to focus on the purpose of the API rather than lower-level details such processing HTTP requests. 

We’re not going to focus on libraries used to create APIs in this lesson. We’re going to keep this programming language agnostic. Allowing specific libraries to be taught in a more specific context. Building and maintaining long-term REST APIs requires a non-trivial amount of effort. Let’s take a look at some of the tools and standards surrounding REST APIs. 

There are a couple API definition mechanisms which are used for defining REST APIs in a programming language-agnostic manner. This can be highly useful for APIs which use a single interface to interact with resources provided by different services. By defining the API schema in a generic manner each service can be created using programming languages and libraries which make sense for the service and service maintainers. These services can use the generic definition for either code generation and or request validation. 

The first mechanism is called OpenAPI. Here’s what open API has to say about itself:

“The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic”.

OpenAPI has become popular in recent years being used on large-scale APIs at Google, IBM, etc. Here’s an example specification. It provides API designers a way to define the schema in a generic format which can be implemented by API developers in different ways. This example specifies that HTTP GET requests to the URL /pets should return a JSON array. The next API definition mechanism is called RAML. Here’s what RAML has to say about itself:

“RAML was designed to make your life easier by giving you power over the full API Lifecycle by letting you design, build, test, document, and share your REST API with a single source of truth and a large open source community.”

RAML is a YAML-based method of defining a REST API and generating server-side APIs using code generators. Here’s an example of a RAML specification. It’s conceptually similar to the OpenAPI example, though with different structures for defining schema. Let’s take a look at a couple tools which can be used to interact with web and REST APIs. The first tool I want to introduce is called curl. Curl is one the most widely used pieces of software on the internet. Here’s what curl has to say about itself. 

“curl is used in command lines or scripts to transfer data. curl is also used in cars, television sets, routers, printers, audio equipment, mobile phones, tablets, set-top boxes, media players and is the Internet transfer engine for thousands of software applications in over ten billion installations.”

Consider curl to be a command line web browser. It can be used to send HTTP requests and view the response. Being able to send and receive web requests using the command line allows developers to automate different types of testing and debugging. Here’s a real-world example pulled from Mailgun’s API documentation. It demonstrates how to use CURL to make a POST request to mailgun’s API. Curl is so common among software engineers that it’s included in different API documentation. 

The next tool I want to introduce is called Postman. Here’s what Postman has to say about itself:

“Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster.” 

Consider Postman to be a generic user interface for working with all web and REST APIs. It’s designed to make it easier for developers to view and manipulate all the different aspects of requests and responses. When automating or scripting an API request, curl is a logical choice. However, when designing and debugging an API having Postman’s visual interface can help to more fully contextualize what’s happening during the request. 

Okay, this seems like a natural stopping point. Here are some of the key takeaways for this content. 

• There are many software libraries used for creating REST APIs

• These allow developers to focus on the purpose of the API; rather than the implementation of the REST constraints.

• There are different tools which allow REST API schemas to be defined in a programming language-agnostic manner.

• OpenAPI and RAML are two examples.

• There are many tools which can be used to improve API design, development, and debugging.

• Curl and Postman are just two examples.

Alright, that's all for this lesson. Thanks so much for watching and I’ll see you in the next lesson.