Glossary of emite IPaaS Terms

API

An application programming interface (API) defines the rules that you must follow to communicate with other software systems. Developers expose or create APIs so that other applications can communicate with their applications programmatically.

REST

Representational State Transfer (REST) is a software architecture that imposes conditions on how an API should work. REST was initially created as a guideline to manage communication on a complex network like the internet. You can use REST-based architecture to support high-performing and reliable communication at scale. APIs that follow the REST architectural style are called REST APIs. Web services that implement REST architecture are called RESTful web services. The term RESTful API generally refers to RESTful web APIs. However, you can use the terms REST API and RESTful API interchangeably. You can think of a web API as a gateway between clients and resources on the web.

• Clients are users who want to access information from the web. The client can be a person or a software system that uses the API. For example, developers can write programs that access weather data from a weather system. Or you can access the same data from your browser when you visit the weather website directly.

• Resources are the information that different applications provide to their clients. Resources can be images, videos, text, numbers, or any type of data. The machine that gives the resource to the client is also called the server. Organizations use APIs to share resources and provide web services while maintaining security, control, and authentication. In addition, APIs help them to determine which clients get access to specific internal resources.

URL

URL means Uniform Resource Locator, which is the address to not just identify a resource, but also to specify how to access it. In an API, the URL can be named as Base URL, which means that is the base address that will be used in every request. For example: http://api.example.com. URI means Uniform Resource Identifier, which is used in the URL to specify which resource the Client would like to access in a request. For example: http://api.example.com/products

• URL: http://api.example.com/

• URI: /products

Therefore, every URL is an URI, but not all URIs are URLs.

Parameters

Parameters are information that can be sent in a request by the Client in order to influence the response by the Server. REST has 4 types of parameters, and its use will depend on the type of action that the request demands.

• Body Params - the Body, like the name says, it’s the body of the request which contains all the data that the Server needs to successfully process the request. Therefore, it’s only used in requests that must send information, such as create or update.

• Route Params - Route params are parameters inserted in the URL with the information to identify a specific resource in order to take an action, such as: retrieve, edit, update or delete.

• Query Params - Query params are also parameters inserted in the URL, but with the main difference that it’s use cases are related to filter and search information about a resource, or even paginate and ordinate the results.

• Headers - Headers allows sending extra information in a request, such as authentication tokens and content types.

HTTP

The HTTP Protocol determines not just the methods that are allowed in a REST API, which means the action types that the Client can demand in a request, but also the status codes that the Server returns as a response to have a good communication flow.

There are 5 main methods that a Client can use in a request in order to manipulate an API resource, which are related with the 5 basic data manipulation types in a database, such: Create, Retrieve, Update and Delete.

• GET - This method is used to retrieve data from a Server by indicating the resource in the URL. For example, to request a list of products of an API, the Client might send:

• POST - This method is used to create a new resource in the Server by indicating it in the URL and sending the resource data in the request body.

• PUT - This method is used to update a resource data in the Server by identifying it in the URL, and sending the information that will be updated in the request body.

• PATCH - This method is also used to update a resource data in the Server by identifying it in the URL, but with the main difference of updating just a specific information.

• DELETE - This method is used to delete a resource in the Server by identifying it in the URL.

The HTTP Status Codes are codes returned by the Server in order to indicate the type of response in a Client’s request, facilitating the understanding just by its group and number. The most commonly used groups and numbers of status code are:

• Success:

  • 200 OK: Everything worked as expected. Your request was successful, and the API returned the data you asked for.  

  • 201 Created: A new resource was successfully created in response to your request (like adding a new user).  

  • 204 No Content: The request was successful, but there's no content to return in the response body (e.g., deleting a record).  

• Client Errors:

  • 400 Bad Request: Something was wrong with your request, like missing data or incorrect formatting. The API couldn't understand what you wanted.

  • 401 Unauthorized: You need to authenticate (prove your identity) before accessing this resource. This usually means providing an API key or logging in.  

  • 403 Forbidden: You're authenticated, but you don't have permission to access this resource.  

  • 404 Not Found: The resource you requested doesn't exist. Double-check the URL for typos.  

  • 429 Too Many Requests: You've sent too many requests in a given time period. The API is rate-limiting you to prevent overload.  

• Server Errors:

  • 500 Internal Server Error: Something went wrong on the server-side. This is a general error that doesn't tell you much about the specific problem.  

  • 502 Bad Gateway: The server acting as a gateway or proxy received an invalid response from an upstream server.  

  • 503 Service Unavailable: The server is temporarily unable to handle your request, perhaps due to maintenance or overload.  

Understanding these status codes helps you troubleshoot issues and ensure your API interactions are running smoothly.

JSON

JSON (JavaScript Object Notation) is a simple text-based format for representing data as key-value pairs and ordered lists. It's designed to be easy for both humans and machines to understand, making it ideal for transmitting data between web servers and applications, like when interacting with APIs. JSON's flexibility, efficiency, and wide support across different programming languages have made it a popular choice for data exchange on the web.

API Pagination

When dealing with REST APIs that return large datasets, pagination is essential to manage the amount of data transferred at once. It breaks down results into smaller, more manageable chunks, improving performance and user experience. Think of it like browsing a catalog – instead of displaying every item at once, you view a few pages at a time. APIs use pagination parameters in the request to specify which "page" of results you want.  

Common types of pagination include:

• Page-number based: You request a specific page number with a predefined page size.

• Offset based: You specify the starting point (offset) and the number of records to retrieve.  

• Cursor based: You receive a unique cursor with each response, which you use to fetch the next set of results.  

• Time based: You retrieve records based on a timestamp, fetching data from a specific time interval.  

• Keyset based: This method uses a "key" from the last retrieved record to fetch the next set of results, offering efficiency for large datasets.

The best approach depends on your API and the specific data you're accessing.

Data Mapping and Transformation

Data mapping is the process of defining how data from one system (source) should be transformed and structured to match the requirements of another system (target). It's like creating a translation guide for your data, ensuring that information flows seamlessly between different applications and formats. This involves matching fields, transforming data types, and applying rules to ensure data integrity and consistency across your integrated systems.

API Throttling and Rate Limiting

API throttling and rate limiting are common strategies used by API providers to control the flow of traffic and prevent abuse. Throttling typically limits the number of API calls a user or application can make within a specific timeframe, such as a certain number of requests per second or per hour. Rate limiting, on the other hand, sets a maximum number of requests allowed within a given time window, such as a day or a month.

These mechanisms are crucial to ensure fair usage, prevent overload, and maintain the stability and performance of the platform. When integrating with various APIs, it's important to be aware of the throttling and rate limits imposed by each API provider and configure your integrations accordingly to avoid exceeding those limits. This may involve implementing strategies like request queuing, error handling, and retry mechanisms to gracefully handle throttling situations and ensure smooth data flow across your integrations.

emite IPaaS Tenant

An IPaaS Tenant provides a secure and logical separation between end-client integrations.

emite IPaaS Integration

An IPaaS Integration establishes a connection to one or mote external data sources, facilitating the retrieval and utilization of data for analysis and reporting. An Integration can consist of one or more Actions.

emite IPaaS Action

An IPaaS Action defines a specific API call made to the integrated data source to retrieve data, such as an Authentication request or a call to retrieve aggregate or detailed data.