This article is focused on Integration API and the terms used when discussing it. The information presented here is offered from the perspective of using Integration API alongside Absorb LMS.

For more information about using our Integration API please advise the following article:

• Getting Started with the Absorb Integration API

A REST API adheres to the constraints of the REST architectural style. It serves as an application programming interface (API) that enables secure and efficient communication between two computer systems over the internet. Let’s break down the key components:

1. API (Application Programming Interface): An API defines rules for communication between different software systems. Developers create APIs to allow other applications to interact with their own applications programmatically. For instance, an internal time sheet application might expose an API that retrieves an employee’s work hours for a specific date range.
2. Clients: Clients are users or software systems that access information from the web. They use APIs to request resources (such as data) from servers. For example, a weather application can be a client that fetches weather data from a weather system.
3. Resources: Resources are the information provided by various applications to their clients. These resources can be images, videos, text, numbers, or any type of data. The server (the machine providing the resource) shares these resources with clients via APIs.
4. REST (Representational State Transfer): REST is a software architecture that defines how APIs should work. It was initially designed to manage communication on complex networks like the internet. REST APIs follow REST principles, which emphasize scalability, reliability, and cross-platform portability. They provide a flexible way to integrate applications and connect components in micro-services architectures.

In summary, a REST API facilitates secure and reliable communication between systems by adhering to REST guidelines. It acts as a gateway, allowing clients to access resources on the web while maintaining security and control.

API

An Application Programming Interface (API) serves as a bridge between different software systems, allowing them to communicate and exchange data, features, and functionality. Here are the key points:

• Definition: An API is a set of rules or protocols that enable software applications to interact with each other. It defines how requests and responses should be structured for seamless communication.
• Purpose: APIs simplify application development by allowing developers to integrate data, services, and capabilities from other applications. Instead of building everything from scratch, developers can leverage existing APIs.
• Communication: When a client (such as a web application) needs to access information from a server, it sends an API request. The server processes this request and sends back a response containing the requested data.
• Example: Consider third-party payment processing. When a user clicks “Pay with PayPal,” an API call retrieves information. The API communicates with the external payment system, receives the data, and seamlessly transfers it back to the product website.
• Benefits:
  • APIs connect different platforms and apps, automating workflows and improving collaboration.
  • Companies can make connections with new partners and access new markets.
  • APIs prevent information silos and enhance productivity and performance.

In summary, APIs facilitate secure communication between software systems, making data exchange efficient and reliable.

API Key

An API Key is a code passed in by computer programs calling an API to identify the calling program, its developer, or its user to the website. API keys are used to track and control how the API is being used, for example, to prevent malicious use or abuse of the API.

The API key often acts as both a unique identifier and a secret token for authentication, and will generally have a set of access rights on the API associated with it. API keys can limit access to only certain types of calls, services, or data. They can also be used to track how many requests have been made and charge users based on their usage.

For example, a developer might use an API key to request data from a service like Google Maps or Twitter. The key is sent in the request header and tells the API that the request is coming from a trusted source, allowing the developer to access the requested data.

API keys are a vital part of web development and are used to ensure secure communication between systems.

Authentication

API authentication is the process of verifying the identity of a user who is making an API request. It is a crucial pillar of API security, as it helps to protect sensitive data, build trust with users, and safeguard the reputation of the API provider. Here are the main points:

• Client-Server Interaction: When two software applications need to integrate over the internet, one application (the client) sends a request to the other application’s API. The client might request a resource from the app’s database or ask to perform an action on the server.
• Authentication: Authentication is the process of confirming that the client is who they claim to be before granting them access to the API. Authentication can be done using various methods, such as Basic Authentication, API Key, OAuth, or JWT (JSON Web Token).
  • For example, Basic Authentication requires the client to send the username and password in the header of the request, while OAuth requires the client to obtain an access token from an authorization server and send it in the header of the request.
• Benefits: API authentication has several benefits, such as:
  • Data Protection: API authentication prevents unauthorized users from accessing or modifying sensitive data, such as personal information, financial transactions, or confidential documents.
  • User Trust: API authentication ensures that users can trust the API provider and the applications that use the API. Users can control their data and permissions, and revoke access if needed.
  • Reputation: API authentication enhances the reputation of the API provider and the applications that use the API. It demonstrates that they care about security and privacy, and comply with regulations and standards.

In summary, API authentication is a way for APIs to verify the identity of the clients that access them. It is an essential part of API security, as it protects data, users, and reputation.

Authorization

API authorization is the process of checking whether a user or a client has the necessary permissions to access specific resources or functions in an API. It is a critical part of API security, as it ensures that only authorized users or clients can access sensitive data and functionality. Here are the main points:

• Client-Server Interaction: When two software applications need to integrate over the internet, one application (the client) sends a request to the other application’s API. The client might request a resource from the app’s database or ask to perform an action on the server.
• Authorization: Authorization is the process of granting or denying access to specific resources or functions in an API based on the permissions and policies associated with the client. Authorization can be done using various methods, such as Role-Based Access Control (RBAC), Attribute-Based Access Control (ABAC), or Policy-Based Access Control (PBAC).
  • For example, RBAC assigns roles to users and grants permissions based on their roles, while ABAC grants permissions based on the attributes of the users, the resources, and the environment.

In summary, API authorization is a way for APIs to control the access to their resources and functions. It is an essential part of API security, as it protects data, users, and reputation.

Call

An API Call may be referred to as simple a Call or the functionality it is calling such as a GET or POST.

An API call is a request sent by a software application to another application’s API to access or manipulate data, features, or functionality. Here are the key points:

• Request Format: An API call is usually an HTTP message that follows a specific format. It consists of a method (such as GET, POST, PUT, or DELETE), a URL (the endpoint that identifies the resource or service), and optionally, a body (the data or parameters of the request).
• Response Format: The API responds to the API call by sending back an HTTP message that also follows a specific format. It consists of a status code (such as 200, 404, or 500), a header (the metadata about the response), and optionally, a body (the data or result of the request).
  • Example: Consider an API call to get the current weather information for a city. The client might send a GET request to the URL https://api.weather.com/v1/city?name=Calgary. The API might respond with a status code of 200, a header that indicates the content type is JSON, and a body that contains the weather data in JSON format.

In summary, an API call is a way for software applications to communicate and exchange data, services, and capabilities over the internet. It is how different applications talk to each other.

Endpoint

An API endpoint is a digital location where an API receives requests about a specific resource on its server. In APIs, an endpoint is typically a uniform resource locator (URL) that provides the location of a resource on the server.

• Endpoint URL: The client specifies an endpoint as a URL in its request. This URL tells the server, “The resource I want is at this location.” Just like how web browsers load web pages by sending a URL to a web server, the client needs the right endpoint URL to request a particular resource from an API.

In the context of Absorb LMS, an endpoint looks like:

https://rest.myabsorb.com/authenticate

In summary, an API endpoint acts as the point of contact between an API client and an API server. It provides the location where specific resources can be accessed.

Enum

In the context of REST APIs, an enum (short for enumeration) refers to a variable type that has a limited set of possible values.

• What Is an Enum?:
  
  • An enum is a way to define a named set of constant values. These values represent a specific type or category.
  • Enums are commonly used to represent fixed sets of options or states within an application or system.
• Use Cases in REST API Design:
  
  • In REST API design, enums are often used to:
    
    • Define allowable values for certain properties or parameters.
    • Communicate a limited set of possible choices for a given field.
    • Improve type safety by ensuring that only valid values are used.
• Example:
  • Our Integration API documentation indicates if an integer is an Enum. The represented values will also be captured. In this case, 0 = Username and 1 = ExternalId
  • 

Service Gateway

An API service gateway is a software component that acts as a single point of entry for clients to access multiple back end services in a distributed system. It typically performs the following functions:

• Routing: It directs client requests to the appropriate service based on the endpoint URL and the HTTP method (such as GET, POST, PUT, or DELETE).
• Aggregation: It combines data from multiple services and returns a unified response to the client.
• Transformation: It converts data formats between the client and the service, such as JSON to XML or vice versa.
• Authentication: It verifies the identity of the client and ensures that only authorized users can access the services.
• Authorization: It enforces access policies and permissions for different services and resources.
• Security: It protects the services from malicious attacks and provides encryption, firewall, and threat detection features.
• Monitoring: It collects metrics and logs about the performance, availability, and usage of the services.
• Load Balancing: It distributes the workload among multiple instances of the same service to optimize resource utilization and prevent service failures.

An API service gateway can simplify the development and management of complex and scalable systems by providing a consistent and secure interface for clients. It can also improve the performance and reliability of the system by reducing network latency and handling failures gracefully.

Header

An API header is a part of an HTTP message that contains additional information about the request or response. It consists of a key-value pair that follows a specific format. Here are the main points:

• HTTP Message: An HTTP message is a text-based communication between a client (such as a web browser) and a server (such as an API). It can be either a request (sent by the client to ask for a resource or an action) or a response (sent by the server to provide the requested resource or the result of the action).
• Header Section: An HTTP message has two main sections: the header section and the body section. The header section contains metadata about the message, such as the content type, the content length, the date, the authorization, and the cookies. The body section contains the actual data of the message, such as the HTML code, the JSON data, or the image file.
• Header Format: An HTTP header follows a standard format: Header-Name: Header-Value. The header name is a case-insensitive string that identifies the type of the header. The header value is a string that provides the details of the header. For example, Content-Type: application/json is a header that indicates the message body is in JSON format.
• Header Types: There are different types of headers, depending on their purpose and scope. Some common types are:
  • General Headers: These headers apply to both requests and responses, and provide general information about the message, such as the date, the connection, and the transfer encoding.
  • Request Headers: These headers apply only to requests, and provide information about the client, the resource, and the conditions of the request, such as the host, the user-agent, the accept, and the cache-control.
  • Response Headers: These headers apply only to responses, and provide information about the server, the resource, and the status of the response, such as the server, the content-type, the content-length, and the location.
  • Entity Headers: These headers apply to both requests and responses, and provide information about the message body, such as the content-encoding or the content-language.

In summary, an API header is a piece of metadata that accompanies an HTTP message and provides context and instructions for the communication between the client and the server.

Resource

An API resource is an object that represents a specific type of data, service, or functionality in an API. It has a unique identifier, associated data, relationships to other resources, and a set of methods that operate on it. Here are the main points:

• Resource: A resource is the core concept in any Integration API, which is a common style of designing APIs. A resource can be any entity that has a meaning and can be identified, such as a user, a product, a category, or a transaction. A resource can also be more abstract, such as a service, a transformation, or a calculation.
• Identifier: A resource is identified by a Uniform Resource Identifier (URI), which is a string that specifies the location of the resource on the server. A URI can be further divided into a Uniform Resource Locator (URL), which provides the address of the resource, and a Uniform Resource Name (URN), which provides the name of the resource.
  • For example, https://api.example.com/users/123 is a URI that consists of a URL (https://api.example.com/users) and a URN (123).
• Data: A resource has associated data that describes its attributes, properties, or state. The data can be represented in various formats, such as JSON, XML, or HTML.
  • For example, a user resource might have data such as name, email, age, and location.
• Relationships: A resource can have relationships to other resources, which indicate how they are connected or related. The relationships can be expressed using links, references, or embedded data.
  • For example, a product resource might have a relationship to a category resource, which indicates the type of the product.
• Methods: A resource has a set of methods that define the actions that can be performed on it. The methods are usually based on the HTTP verbs, such as GET, POST, PUT, PATCH, or DELETE.
  • For example, a GET request to https://api.example.com/users/123 retrieves the user resource with the ID 123, while a DELETE request to the same URI deletes the user resource.

In summary, an API resource is a way of organizing and presenting information in an API. It is how different applications exchange data and functionality over the internet.

HTTP Method

In the context of APIs, HTTP methods play a crucial role in determining the action an API client wants to perform on a specific resource. These methods are also commonly referred to as HTTP verbs.

Let’s explore some of the key HTTP methods:

• GET: The GET method requests a representation of a specified resource. It is primarily used for retrieving data from the server. When you make a GET request, you expect to receive information without causing any side effects on the server.
• HEAD: Similar to GET, the HEAD method asks for a response identical to a GET request, but without the actual response body. It’s useful for checking metadata (such as headers) without fetching the entire content.
• POST: The POST method submits an entity (usually in the form of data) to a specific resource. It often leads to a change in state or side effects on the server.
  • For example, creating a new resource or submitting a form data.
• PUT: The PUT method replaces all current representations of the target resource with the request payload. It is commonly used for updating existing resources.
• DELETE: As the name suggests, the DELETE method deletes the specified resource from the server.
• CONNECT: The CONNECT method establishes a tunnel to a server identified by the target resource. It is typically used for proxying purposes.
• OPTIONS: The OPTIONS method describes the communication options available for the target resource. It provides information about supported methods, headers, and other capabilities.
• TRACE: The TRACE method performs a message loop-back test along the path to the target resource. It’s mainly used for diagnostic purposes.
• PATCH: The PATCH method applies partial modifications to a resource. It allows you to update specific fields without replacing the entire resource.

Remember that choosing the appropriate HTTP method depends on the specific use case and the desired action you want to perform on the API resource. Whether you’re creating, reading, updating, or deleting data, these methods help define the interaction between clients and servers in the API world. Absorb's API documentation for the Integration API includes the HTTP Method associated with each available function:

Response/Payload

In the context of APIs, an API response refers to the data or information returned from a server when an API request is made. Let’s delve into the details:

• HTTP Status Codes: An API response is closely tied to the HTTP status code sent by the server. Each response corresponds to a specific status code, indicating the outcome of the request. Common status codes include:
  
  • 200 OK: Indicates a successful request.
  • 400 Bad Request: Signifies an invalid or malformed request (e.g., missing parameters).
  • 401 Unauthorized: Denotes that authorization information is missing or invalid.
  • 404 Not Found: Indicates that the requested resource was not found.
  • 5XX (e.g., 500 Internal Server Error): Represents unexpected errors on the server side.
• Response Body: The schema keyword describes the structure of the response body. It can define:
  
  • An object or an array: Typically used with JSON and XML APIs.
  • A primitive data type (e.g., number or string): Used for plain text responses.
  • A file (e.g., binary data).
• Example Scenarios: GET Request for User Data.
  
  • Endpoint: /users/{userId}
  • Response:
    
    • Status Code: 200 (OK)
    • Content Type: application/json
    • Schema: An array of user objects (e.g., { "id": 123, "username": "john_doe" }).

The Absorb LMS API documentation for the Integration API includes Response Samples varying between what to expect from a successful call, or from an error.

JSON

JSON, which stands for JavaScript Object Notation, is a lightweight data-interchange format that is easy for humans to read and write, and easy for machines to parse and generate. In the context of APIs, JSON is commonly used as a format for sending and receiving data.

When an API is called, the server sends a response, often in JSON format. This response could include various types of data, such as strings, numbers, arrays, or objects, which represent the state of the resource being accessed or manipulated through the API.

For example, if you were to make a GET request to the Absorb user endpoint, the JSON response might look something like this:

{
"id": "string",
"departmentId": "string",
"firstName": "string",
"middleName": "string",
"lastName": "string",
"username": "string",
"password": "string",
"emailAddress": "string",
"externalId": "string",
"ccEmailAddresses": [
"string"
],
"languageId": 0,
"gender": 0,
"address": "string",
"address2": "string",
"city": "string",
"provinceId": "string",
"countryId": "string",
"postalCode": "string",
"phone": "string",
"employeeNumber": "string",
"location": "string",
"jobTitle": "string",
"referenceNumber": "string",
"dateHired": "2024-03-01T18:30:10Z",
"dateTerminated": "2024-03-01T18:30:10Z",
"dateEdited": "2024-03-01T18:30:10Z",
"dateAdded": "2024-03-01T18:30:10Z",
"lastLoginDate": "2024-03-01T18:30:10Z",
"notes": "string",
"customFields": {
"decimal1": 0,
"decimal2": 0,
"decimal3": 0,
"decimal4": 0,
"decimal5": 0,
"string1": "string",
"string2": "string",
"string3": "string",
"string4": "string",
"string5": "string",
"string6": "string",
"string7": "string",
"string8": "string",
"string9": "string",
"string10": "string",
"string11": "string",
"string12": "string",
"string13": "string",
"string14": "string",
"string15": "string",
"string16": "string",
"string17": "string",
"string18": "string",
"string19": "string",
"string20": "string",
"string21": "string",
"string22": "string",
"string23": "string",
"string24": "string",
"string25": "string",
"string26": "string",
"string27": "string",
"string28": "string",
"string29": "string",
"string30": "string",
"datetime1": "2024-03-01T18:30:10Z",
"datetime2": "2024-03-01T18:30:10Z",
"datetime3": "2024-03-01T18:30:10Z",
"datetime4": "2024-03-01T18:30:10Z",
"datetime5": "2024-03-01T18:30:10Z",
"bool1": true,
"bool2": true,
"bool3": true,
"bool4": true,
"bool5": true
},
"roleIds": [
"string"
],
"activeStatus": 0,
"isLearner": true,
"isAdmin": true,
"isInstructor": true,
"supervisorId": "string",
"hasUsername": true
}

This JSON response includes an object with the user’s id, name, email, and roles. It’s structured in a way that’s easy for developers to understand and use in their applications.

JSON is favored in API development due to its compatibility with most programming languages, making it a versatile choice for web services and applications.

Pagination

Pagination in the context of APIs refers to the process of dividing a large dataset into smaller, manageable chunks or “pages” of data. It is a common technique used to improve the performance and usability of web applications that handle large volumes of data.

Here’s how pagination typically works in an API:

• Request Parameters: The client sends a request to the API with parameters indicating the size of the page (number of items per page) and the page number or offset (starting point of the data).
• Server Response: The server processes the request, retrieves the appropriate subset of data, and returns it to the client along with pagination details such as the current page, total number of pages, and total number of items.
• Client Navigation: The client can navigate through the dataset by making subsequent requests with updated page numbers or offsets.

Pagination helps in:

• Reducing server load by limiting the amount of data transferred per request.
• Enhancing user experience by providing a structured way to navigate through data.
• Allowing clients to fetch data incrementally, as needed.

APIs often use query parameters like page and limit or offset and limit to implement pagination.

For example, a paginated API call may look like this:

 https://[path]/[endpoint]?_offset=0&_limit=100 

_limit

In the context of REST APIs, the _limit parameter is used to specify the maximum number of resources that a single response page should contain.

• Purpose:
  • When you query a REST API for a collection of resources (such as a list of articles, users, or products), the server might return a large number of items.
  • To prevent overwhelming the client application with too much data in a single response, pagination is commonly used.
  • The _limit parameter allows you to control how many resources are included in each response page.
• Usage:
  
  • When making a request to a REST API endpoint that supports pagination, you can include the _limit parameter in the query string.
  • For example:

    https://[path]/[endpoint]?_offset=0&_limit=10

  • This request asks the server to return a maximum of 10 articles in the response.
• Pagination:
  
  • Along with _limit, you often use other parameters like _offset to implement pagination.
  • _offset specifies the starting index of the resources.
  • By combining these parameters, you can navigate through the entire collection of resources.

_offset

In the context of REST APIs, the _offset parameter plays a crucial role in pagination.

• Purpose of _offset:
  
  • The _offset parameter allows you to skip a certain number of items in a resource collection before returning the requested data.
  • It’s commonly used when you want to retrieve a specific subset of results from a larger dataset.
• How It Works:
  
  • When making an API request, you can include _offset in the query string.
  • The server then starts fetching resources from the collection after skipping the specified number of items.
  • For example, if you set _offset=10, the API response will begin with the 11th item in the collection.
• Use Cases:
  
  • Combining _offset with other parameters like _limit (which specifies the maximum number of items per page) allows you to implement pagination.
  • Suppose you’re displaying search results or a list of items in a user interface. As the user navigates to subsequent pages, you adjust the _offset value to fetch the next batch of results.
• Example:
  
  • Let’s say you have an API endpoint that returns a list of blog posts. To retrieve the second page (items 11 to 20), you might use:

  • GET /api/posts?_limit=10&_offset=10

Token

An API Token is a unique identifier used for the purpose of authentication when making API requests. It acts as a security key that grants access to specific resources or functionalities provided by an API. Here’s a breakdown of what an API token is:

• Unique Code: An API token is a string of characters that uniquely identifies a user or application. It’s like a digital key that allows access to an API’s features and data.
• User-Specific Information: API tokens often contain information specific to the user or application that is using it. This can include permissions, user roles, and other relevant data.
• Device-Specific: Tokens are usually tied to a particular device or session. For example, a user might have one token for their smartphone and a different token for their desktop application.
• Security: API tokens are an important part of securing APIs. They ensure that only authorized users or applications can access the API, helping to prevent unauthorized use.
• Scope of Access: The token also defines the scope of access that is granted, which means it specifies what resources and operations the token holder can perform.

In essence, API tokens are crucial for managing the security and access control of APIs, ensuring that only authenticated and authorized requests are allowed to interact with the API.