RESTful API Foundations

API foundations

This article provides fundamental information about what an API can do so that you can understand how using APIs can benefit your company. There will be a particular focus on RESTful APIs since this is what Aspire uses. 

What is an API?

Restaurant analogy 

• The reservation authorizes the use of the menu.  
• The menu symbolizes API documentation that lists available services and data the API provides.  
• As a patron, you represent the client making requests by ordering from the menu.
• The waiter represents the API and communicates between you and the kitchen staff. 
• The kitchen staff represents the server on the backend.
• The kitchen staff (server) responds through the waiter (API) to deliver what you, the patron (client), requested.

This analogy only serves the high-level purpose of illustrating the concept of an API and definitely does not cover all of the information needed to understand the inner workings of an API fully. 

Fundamental API components 

The External Aspire API described in this guide is a web-based RESTful API that uses HTTP protocol and JSON data format and is secured via bearer authentication. The information below describes what this means in greater detail. Now that we can grasp the concept of an API, we can break down fundamental information about RESTful APIs.

 Below is a breakdown of each of these categories as it relates to the Aspire External API:

HTTP protocol 

HTTPS is a secured version of HTTP.  

• URL (Uniform Resource Locator) - a unique address the client uses to tell the server what they want and how to interact with it. 
• Method - the method indicates the action that the server should take. There are four different available HTTP methods used in the Aspire External API: 
  • GET - retrieves information from a resource.  
  • POST - adds new information to a resource. 
  • PUT - modifies information existing within a resource. 
  • DELETE - removed information from a resource using an endpoint. 
• Headers - provide information in the request, such as the data format specification and authorization details. The information provided appears in the form of key-value pairs. 
• Body - contains information that the client is sending to the server. When using PUT and POST methods, the body contains the information you want to change or add to the server. Delete and GET do not contain a body. 

• Status Code - the status code is a number used to indicate the type of outcome yielded by the response. For example, a 200 status code will be returned to indicate that the request sent was successful. 
• Body - the body contains the requested information.
• Header - provides information about the response, such as data format and Accept, which indicates the server authorizes the client. 

RESTful architectural style

REST is an architectural style based on principles provided by Roy Fielding that intend to guide but do not require complete adherence. In most cases, it makes more sense to call REST APIs RESTful since there is no requirement to adhere to REST principles completely, and they are often incorporated with protocols, such as OData. When a protocol is incorporated with a REST API, the rules and syntax outlined by the protocol must be followed.

Within a RESTful API, the client requests access to interact with what is known as a resource from the server using endpoints. An endpoint represents the resource and the action to be taken with that resource via a specific URL or URI. A method coupled with an endpoint expresses what action should be taken with the resource. A resource within REST APIs typically represents a data concept or service within a system. Tasks, Services, and Branches are resources within a field service application. Specific components within a resource are called objects. Resources can be nested with other resources. You will find a few examples of this within the Aspire External API. 

Request parameters

When constructing requests you can use query parameters to filter and sort information. This parameter is used with the GET method, which retrieves information. Body parameters can be used to add or change information on the server. This parameter is used with the PUT and POST methods. 

Query parameters

Query parameters are used in requests to filter and manipulate data returned in a response. Usually, they are used to instruct the server to filter and sort the returned data. When looking at a URL, the query parameters will appear as key/value pairs. The format that should be followed when making query parameter statements is dictated by the type of RESTful API in use. OData syntax must be followed when using the Aspire External API.

Body parameters

Body parameters only apply to PUT and POST parameters, representing objects that can be changed or created for a resource when sending a request. Some objects are required when using the POST or PUT method; others are optional and will be denoted as such. 

JSON data format 

JSON was initially created to contain structured data to be used with the Javascript programming language

Data types 

JSON syntax comprises singular data types, arrays (collections), and objects. Click on OpenAPI Guide - Data Types for comprehensive information about the data types relevant to the Aspire External API. 

• Data types- dictate how information can be shared. These are the data types used in JSON:  
  • Strings - enclosed in single or double quotation marks.  e.g. ABCEDFS 
  • Numbers - integer or decimal, positive or negative.  e.g. 1,2,-3, 0 
  • Boolean - true or false does not require quotations.  e.g., True or False
  • null - "nothing" (not to be confused with "empty" does not require quotations. e.g., null 
• Arrays (collections) - are lists that are composed of multiple data types (can be mixed) that are enclosed in brackets [ ] and separated by commas. e.g. [1, True, "hello", 5]
• Objects (dictionaries) - contain key and value separated by a colon, and key/value pairs are separated by a comma and enclosed in curly brackets { }. e.g {"mild":3, "spicy":4, "hot":5}
• Arrays and objects can be nested inside one another. A typical JSON file is an object holding objects and arrays within it. 

Authentication & authorization 

The security of an API consists of: 

• Ensuring only authorized users have access.
• Controlling which resources can be accessed.
• Limiting the amount of requests that can be made at a given time. 

Authentication is the process of a user providing credentials used to receive an access token. Authorization is the process of sending the access token to a server. 

Commonly OAuth 2.0 and Bearer Authentication are used to secure APIs. The External Aspire API uses a bearer token. 

Conclusion

Understanding these concepts will help you tap into the full potential of the Aspire External API. View the listed resources to gather more helpful information that is comprehensive:

• RedHat - What is an API? 
• An Overview of HTTP
• What is a REST API
• OData
• JSON
• Bearer Authentication