REST API Uses

Name: REST API Uses
Author: Josh Guardino

Learn how to use OpenAPI documentation and perform common operations

Preview the first lesson free — get full access to all 4 lessons.

Course: On-Demand

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.

Beginner Provider : Josh Guardino 4 Lessons · 24m in Arabic, German, English, Spanish, French, Portuguese, Chinese

Course Description

REST is an API architectural style that relies heavily on industry standards as well as the core foundational concepts that power the internet. This approach allows for common, repeatable usage patterns and fits with widely accepted standards for API access and documentation. Many prepackaged modules and templates exist for REST APIs, but it is also possible—and in fact commonplace—for REST APIs to be created from scratch.

Many API documentation formats exist, but the most common and perhaps the easiest to use is called OpenAPI. It allows owners of REST APIs to publish interactive documentation that is automatically generated based on the capabilities of the API. You will learn how to read OpenAPI documentation and run API tests directly from it.

The most prevalent types of API actions and HTTP methods are covered, including read operations using the GET method, send operations using the POST method and update methods using the PUT, PATCH and DELETE methods.

What You'll Learn

Describe the purpose and format of OpenAPI documentation, including how to read it and run API tests directly from it
List and describe the most common HTTP methods used with REST APIs
Perform read operations by understanding how GET requests receive data from REST APIs
Send and update data by identifying how write requests pass request bodies to REST APIs
Use POST requests to send operations to REST APIs
Update object state using the PUT, PATCH, and DELETE methods

Key Takeaways

REST is an API architectural style that relies on industry standards and the core foundational concepts that power the internet, enabling common, repeatable usage patterns.
REST APIs can be built using prepackaged modules and templates, but it is also commonplace to create them from scratch.
OpenAPI is the most common and arguably easiest API documentation format, and it lets REST API owners publish interactive, automatically generated documentation based on the API's capabilities.
GET is used for read operations, POST is used for send operations, and PUT, PATCH, and DELETE are used for update operations.
Write requests send request bodies to REST APIs, while GET requests receive data from them.

Frequently Asked Questions

What does this course cover?

It covers the REST API architectural style, how to read OpenAPI documentation and run API tests from it, and the most prevalent API actions and HTTP methods, including GET for read operations, POST for send operations, and PUT, PATCH, and DELETE for update operations.

What HTTP methods will I learn about?

The course covers the most common HTTP methods, including the GET method for reading data, the POST method for sending data, and the PUT, PATCH, and DELETE methods for updating object state.

What is OpenAPI and how is it used in this course?

OpenAPI is the most common API documentation format, allowing REST API owners to publish interactive documentation that is automatically generated based on the API's capabilities. In this course you will learn how to read OpenAPI documentation and run API tests directly from it.

What lessons are included in this course?

The course includes four lessons: OpenAPI Documentation, GET Requests, POST Requests, and Updating Object State Using HTTP Methods.

What skills does this course help develop?

It supports skills such as API Design, API Management, REST API Development, RESTful API, Rest Client, and Advanced Rest Client.