REST API Uses

Transcript of the free preview lesson. Remaining lessons unlock with the full course.

In this lesson, I will show you how to read and use OpenAPI documentation. There are many types of documentation systems for REST APIs but the best known and most widely used is called the OpenAPI Specification. OpenAPI was first introduced by Swagger, which is an API toolset. The standard is now maintained by a group called the OpenAPI Initiative, which is a consortium of experts in the API technology field. The OpenAPI Initiative publishes a specification that dictates how OpenAPI documentation should look and function. Let's take a look at a reference implementation of OpenAPI, which is hosted by Swagger. It's called the Swagger Petstore, and it is a sample scenario involving pets, stores and users. This documentation format is meant to be very easy to read, comprehensive, and with the ability to test out each API from within the documentation itself. The various HTTP methods that are supported are color coded. GET requests are blue, POST requests are green, PUT requests are orange, and DELETE requests are red. Although these colors can be customized, these are the standards. By clicking on each endpoint, you can view all of the details of that particular endpoint within the API. For example, parameters that might be passed to the API: sample request bodies, supported document transfer types, such as JSON or XML, sample response bodies for each type of response code and query parameters that may be passed to the API. Also, at the bottom of an OpenAPI specification document, you can find the models. These would list the different types of objects that might be included within a response from the server. By clicking through, one can see the various attribute names and data types. Let's try out one of these services. If we click on the GET request for finding pets by ID, we can see that it accepts one parameter, which is required called petId. It is an integer, meaning it has to be a whole number. So let's click the try it out button and enter an ID in the field. Let's click execute. And a few things happen. First of all, the curl request is shown. Curl is a command line program that is built into most operating systems. It allows you to issue requests to any type of HTTP service by passing a variety of arguments to the curl executable. So in this case, the OpenAPI URL specified was /pet/ curly brace, petId, closing Curly brace. Variable names shown within curly braces are intended to be replaced with actual values. And API endpoints always begin with a forward slash, which would be appended to the root URL of the API. As we can see here, the root URL is https://petstore.swagger.io/v2. The v2 here stands for version two and this is the way that API versioning is usually handled. The -H stands for headers, and in this case, we are sending a simple accept header, which tells the server which type of document format we would prefer that the results are stored within. Next, we see the response that was issued from the server. The status code here is 200, which means that the request was successful and what we have here is a response body in the JSON format and the various fields are populated with the values that were retrieved from the server. This will then represent the state of this particular object at this point in time. Below the response body are response headers. This is meta information about the request that helps provide more information about the request itself. Now, let's try to test this API with an invalid pet ID. The OpenAPI documentation is able to validate this and not even allow the request to go through. So instead of putting a non-numeric value, let's put in a number that is numeric but is not found on the server. This time, our response is not a 200, it is a 404. 404 is the HTTP status code that is issued when a resource is not found. The various other color-coded HTTP methods and endpoints may be used to pass information to the server to change the state of an object. Generating OpenAPI documentation is a fairly straightforward operation that may be performed from a variety of tools and programming languages. The OpenAPI documentation is not usually created manually by hand, but is generated automatically based on the services that are provided. For example, this JSON document describes the API and would be part of the API's source code. When the API is generated, the specification documents are created automatically based on what is in this file, making comprehensive documentation of any API a simple operation that will stay current automatically with changes to the API itself. Thanks for watching. Stay tuned for the next lesson where I will show you how to issue GET requests to read the state of objects from REST APIs.