To understand the University API, you're going to have to get comfortable with RESTful APIs. There are many excellent articles and books on the subject. For example, simply google "RESTful" and there are dozens of good links including a link to Roy Fielding's dissertation that introduced the concept of Representational State Transfer (REST). This tutorial won't attempt to review all of this information. It assumes that you will gain a working understanding of RESTful APIs on your own.
At the same time, you don't have to be a REST guru to understand and use the University API. Most of the concepts are intuitive and easily understood. You may wish to get started with the tutorial and refer to other additional information on REST as needed. The tutorial does provide links to some useful reference information that you may wish to explore.
So, let's get started.
A RESTful API is based on the HTTP protocol and is built around the concept of resources. The URL describes a resource or a collection (set) of resources. For example, "https://host-name/cars" describes a collection of cars. If you were to invoke an HTTP GET method against this URL, you might expect to receive a collection of cars in a JSON array. Each car in the array represents an item in the collection. A URL of "https://host-name/cars/{vin}" would describe a specific car. If you were to invoke an HTTP GET method against this URL, you would expect to receive only one instance (or perhaps the empty set if the vin is not valid). Sometimes a collection is so large that it is difficult to use. It is possible to filter a collection with the query string portion of the HTTP protocol. For example, "https://host-name/cars?color=red&make=Ford" would return a JSON array that only contains red Fords.
The University API makes extensive use of the HTTP protocol. This includes HTTP methods, HTTP return codes, and HTTP headers.
For a better understanding of HTTP methods, you may wish to refer to this guide provided by W3 Schools. (Note: Pay special attention to idempotent methods. The goal of the University API is for all methods to be idempotent.)
The following table describes how the University API utilizes HTTP methods.
http_method |
description |
notes |
OPTIONS |
Returns the set of http_methods allowed for the URL that addresses a collection. |
According to HTTP protocol the answer is returned in an HTTP header with a key name of "Allow". For example, if a URL allows the GET and POST methods the HTTP header would contain "Allow: GET,POST,OPTIONS". The University API also returns a JSON array in the body that answers the question. The JSON would look like this: { "supported_methods": [ "GET", "POST", "OPTIONS" ] } |
GET |
Returns a collection in a JSON array in the body of the response. |
Sometimes, a combination of query string filters or URL segments may return only one (or even zero) items. That's OK. Even the empty set is a valid set. In the University API, we have elected to always return a JSON array structure even when there is only one or zero items returned. This allows the developer to code for a predictable JSON data structure. We don't change the contract of the return body based on the number of items selected. |
POST |
Creates a new instance of a resource. |
In most instances, the body will contain a single item to be added, but the request body may contain a JSON array structure of resource(s) to be created (added). The return body is the item that was added or a JSON array structure that contains information about each resource for which an add attempt was made. |
PUT |
Modifies the resources defined by the URL based on the contents of the request body. |
While there may be cases where we perform bulk updates, we have tried to avoid them in the University API. Generally, the URL defines a single item instead of a collection and that single item is modified to "look like" the resource in the request body. The modified resource is generally then returned in the return body. |
DELETE |
Delete the resource defined by the URL |
Once again, there may be cases for bulk deletes, but we have tried to avoid them in the University API. Since the URL completely defines the resource to be deleted, there is generally no request body or return body for this method. |
For a better understanding of HTTP return codes, you may wish to refer to this page at the REST API Tutorial site. (While you are there, you may wish to look around at some of the other information. It is a pretty good reference.) The University API will use the proper HTTP return codes to convey information.
For a better understanding of HTTP headers, you may wish to google "http headers". There is an overwhelming amount of good information. The main use of HTTP headers in the University API is to convey authentication/authorization tokens.
A key component in documenting and managing the University API is WSO2's API Manager. It is a powerful and extensive tool. WSO2 provides excellent documentation and tutorials.
This tutorial will only introduce you to the tool by presenting examples in the API Manager. Let's get started.
Don't get confused if the screen looks a bit different. The APIs defined in our WSO2 instance is constantly changing. Find the "Cars" API and left click on it. You should be presented with the following:
The most important thing on this page is the base URL that you would use to invoke the API, which is "https://api.byu.edu/domains/tutorials/cars/v1". For the point of this tutorial, we only published one URL for Production and Sandbox. When dealing with a "real" API, there will probably be two URL's. The parts of the base URL are:
To explore the API, select the "API Console" tab in the middle of the page. You should be presented with the following:
Let's explore one of the operations to get a feel how this works. Left click on the "GET /{vin} Retrieve a Car" operation. You should be presented with the following:
This tells you what parameters are required to invoke this operation and whether they are required are not. It also details what return codes can be expected. To get an idea how WSO2 functions, enter "1CRTW25A3NX78232" as the vin value (by replacing the "{required}" text in the input field) and press the "Try it out!" button. You should be presented with the following:
There are two cool things to be learned from this. First, what is the request URL. The developer can see exactly what needs to go into the custom application. Second, an example of the JSON structure that will be returned.
Go ahead and play with the rest of the operations.
WSO2 provides an interface to define an API. It is OK for learning how WSO2 works, but we will not use it to define the University API. WSO2 also provides the ability to import Swagger 2.0 documents. Swagger is a specification used to define RESTful APIs. There are several advantages to defining the API with Swagger documents, but the most convincing one is that the Swagger community has provided code generators for most programming environments and other utilities to help the consumers of the API. Future tutorials may demonstrate how to generate code from a Swagger document. The Swagger 2.0 specification is the current specification. (You will note that the Swagger 2.0 specification has also been adopted as the official specification of the Open API Specification.)
The Swagger 2.0 document for example 1 can be found at: https://raw.githubusercontent.com/byu-oit-appdev/api-repo-sandbox/master/swagger20/apitutor1/apitutor1.swag20
If you would like to see a Swagger 2.0 document rendered in an editor, this is how you can do it:
The Swagger 2.0 editor allows you to explore the API side-by-side with the Swagger 2.0 document. The WSO2 Publisher uses this same editor when creating an API.
The University API will follow the pattern of this example for all resources.
This sounds great as long as I am working with resources that only contain a few dozen items. Of course, most of the resources in the University API will contain millions of items.
One method to address this is to filter the collection with query parameters. For example ""https://api.byu.edu/domains/tutorials/cars/v1?color=red&make=Ford" would return a JSON array that only contained red Fords. There may be a few APIs in the University API that allow you to filter on any attribute in the return set, but this would be the exception. In most instances, the query parameters that are available and how they can be used are defined by the implementation in the API. The API implementation is built to ensure the performance that would be expected by every consumer of the API.
The query parameters available on an endpoint (HTTP method/URL path combination) are documented in the Swagger documents and can be viewed in the WSO2 API manager. For example, the GET method on the "https://api.byu.edu/domains/tutorials/cars/v1" endpoint supports a large set of query parameters. It looks like this in the WSO2 API Manager:
In this case, most of the query parameters are optional. If a query parameter is required, a "(required)" indicator will appear in the text box. The page_start and page_size query parameters default to 1 and 50 respectively, but may be modified. You may use the "Try it out!" function to see how your URL should be formed, with certain limitations (and possible bugs).
For example, if I type "UT" in plate_state, "ford" in make, and "red" in color and press the "Try it out!" button, the request URL should look like this:
https://api.byu.edu/domains/tutorials/cars/v1/?plate_state=UT&make=ford&color=red&page_start=1&page_size=50
Even with filtering, it is still possible for a result to be so large that it is difficult to work with. Let's suppose that we have 800 red fords with a Utah license plate in our database. A common API technique is to "paginate" large results sets. In our example where page_start=1 and page_size=50, the first 50 items of the result set would be returned. A second invocation where page_start=51 and page_size=50 would be required to retrieve the next 50 items of result set. Caution should be exercised when implementing or using a "pagination" technique. If it is possible that the result set can change between invocations, it is possible that the page boundaries can change and items will be duplicated or dropped in the result set.
You can address a specific instance of a resource by including the resource-key in the URL segment directly after the resource name. For example, to access a specific car with a vin of "1CRTW25A3NX78232", the URL is "https://api.byu.edu/domains/tutorials/cars/v1/1CRTW25A3NX78232".
There are some important concepts in the University API that should be understood here.
The Swagger documents contain definitions using standard JSON schema to define the request/return bodies associated with each API endpoint. These models are visible in WSO2 API Manager. We encourage developers to use the Swagger 2.0 documents and code generator tools available at the Swagger communities web site. This approach make definition and management of the request/return bodies much easier and less error-prone.
As a special note here, and as a guideline, the University API will use the same JSON data structure to PUT or POST information as was returned by the GET operation. In essence, we try to follow the concept that if I GET some information then I should be able to use the same JSON data structure to modify it. One advantage is that this simplifies the mental model required to understand and use an API. A second advantage is that a programmer doesn't have to "translate" from one data structure to another in order to make modification. Hopefully, this simplifies coding and reduces errors.
The Swagger documents contain a tremendous amount of information about the API, and the WSO2 API Manager's "Try it out!" feature allows the consumer to explore the richness of the API. When deemed necessary, and in addition to the Swagger definition files, the API designer should create separate Markdown documents that might help the consumer understand the business flow of invoking certain API resource paths in succession in order to be effective as quickly as possible. Links to these documents are found in the "externalDocs" sections of the Swagger definition file.
These additional documents may address the following kinds of questions:
The feedback box, located below, is intended for general comments on this page or service information and NOT for help with specific technical issues you are having with the service itself. If you would like a response to your feedback, be sure to include your contact information or log into it.byu.edu using the login button at the top of this page.
Services |