RESTful API Foundations
  • 19 Jan 2024
  • PDF

RESTful API Foundations

  • PDF

Article summary

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?

API is an acronym for Application Programming Interface. An API enables two systems that are independent of each other to communicate and interact with each other.  APIs provide value because they do the heavy lifting by saving you time for time-intensive programming tasks. Instead of doing it yourself, you can connect your application to a server holding a program that can instantaneously accomplish the task.  When an API connects different systems, it is called an integration. Integrations occur when a client application and a server on a computer communicate and transmit information to each other. 


With REST APIs, a client system can request to retrieve, add, remove, or change information available on a server. The server is the provider of the API.  The server can respond to the request once it is sent. Before two systems can be integrated, the server must authorize the client. 

Restaurant analogy 

A common analogy that aids in quickly conceptualizing how an API works occurs in a restaurant setting. Imagine you want a good, hearty meal but don't feel like cooking because you don't want to be bothered with finding ingredients. So, you make reservations at a restaurant instead: 


  • 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.

How requests and responses are sent varies and is largely based on the API's protocol and/or design pattern, data format, architectural style, and authentication. A protocol is a set of rules determining how information should be formatted to be sent and received over a network. An architectural style is a set of design principles that determines how an application is structured, organized, and behaves. The data format determines the human-readable format representing the data sent between the client and server, and authentication determines how the API secures communication.  Each component works together to ensure that requests are received from the client to the server and that the server responds to the client given the request sent. 

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

HTTP protocol 

HTTP is an acronym for Hypertext Transfer Protocol, which is a protocol that transmits information between a client and server over the web.  It determines how a request is sent from the client and how a response is received over the web.

HTTPS is a secured version of HTTP.  


When sending a request, the HTTP protocol is made up of four necessary parts to transmit information from the client over to the server: 
  • 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. 
Once the request is sent, the server sends a response containing: 

  • 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 stands for Representational State Transfer.  It is a common architectural style used with web APIs. As mentioned previously, REST APIs use requests and responses to communicate. To reiterate, the client sends a request to the server via the API, and a response is sent from the server to the client via the API. That server then provides you with a return, addition, or modification of information to your application based on the request you sent.  This data transfer occurs through a well-known protocol, HTTP, as discussed above


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 

The data format of an API determines how information appears and is subsequently interpreted. JSON is an acronym for Javascript Object Notation, and it is a text-based format commonly used with web APIs because of the simple structure it requires. 


JSON uses key/value pairs to describe information representing an object. The keys represent the attributes of an object (think of attributes as characteristics of the object), and values describe the attributes. A client and a server must use compatible data formats to transfer information successfully. The data type of a request and a response can be found in the header as content-type. The content type specified for JSON appears as application/json

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:


Was this article helpful?

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.