Skip to main content
Version: 2.2.1

REST API glossary

This article aims to provide a glossary of common terms that you may find when using our REST API. By understanding these terms, you will be able to have a better understanding of how the API works, and thus use its resources more efficiently.

API​

API stands for "Application Programming Interface", an acronym that may not be self-explanatory. Simply put, an API receives input requests and sends output responses. When you make a request to the API, it passes the request on to a server, which processes that request and returns a response. Just as an application's user interface (UI) allows users to interact with the application, an application programming interface (API) allows customers to interact with the application by providing access to its features and resources. Therefore, the API is just another way to interact with the system by offering a simplified interface for the necessary operations.

REST​

REST stands for "REpresentational State Transfer". It is a set of principles and architectural constraints that define the way APIs should be designed to facilitate interaction between software systems. A RESTful API adheres to six specific architectural constraints that ensure requests are processed efficiently, securely, and consistently. These constraints include, among other things, the use of a customer-server architecture, the separation between the interface and the server implementation, and the use of identifiable resources with unique URLs.

Adopting a RESTful approach allows APIs to be developed in a more standardized and interoperable way, simplifying integration between systems. Additionally, architectural constraints help make interaction with APIs easier and less resource-intensive, providing better scalability and performance.

For more information about REST and its architectural constraints, refer to the Representational State Transfer article on Wikipedia, or other specialized software development sources.

JSON​

The SoftExpert Suite API is a JSON-based API, which means it only accepts and returns data in JSON format. The JSON (JavaScript Object Notation) format is a standard way to store and transfer data between different platforms. Although the name refers to JavaScript, JSON can easily be used with other programming languages. JSON has a strict syntax that must be followed correctly, including the proper use of commas, colons, parentheses, and curly brackets (). To illustrate JSON readability, below is an example of a syntactically correct JSON object:

{
  "name": "João",
  "surname": "Silva",
  "age": 30,
  "address": {
    "street": "Rua A",
    "city": "São Paulo",
    "state": "SP"
  },
  "phone numbers": [
    {
      "type": "landline",
      "number": "(11) 1111-1111"
    },
    {
      "type": "mobile",
      "number": "(11) 9999-9999"
    }
  ]
}

CRUD​

Create, Read, Update, Delete. Think of them as verbs. They tell the API to create, read, update, or delete records. On the Internet, the four verbs correspond to HTTP request methods: GET (read), PUT (update), POST (create), DELETE (remove). There are more than these four request methods, but these are the most common. A GET (read) request is the most basic HTTP method. You use it all the time while browsing the web. For example, when you use Google search, your browser sends one GET request after another.

Endpoint​

Endpoints are used to make API calls. As its name suggests, an endpoint is a specific location that receives web requests. An API consists of a collection of endpoints, each of which has its own rules regarding CRUD (Create, Read, Update, and Delete) operations. By understanding the functionality of endpoints and their respective rules, you can use the API more effectively and efficiently.

HTTP response status codes​

When a request is made to an endpoint, the server performs the following steps:

  1. Analyzes the information sent in the request.
  2. Searches for the resource referenced in the request.
  3. Checks whether the user has permission to access the resource.
  4. Returns a response with an HTTP status code.

HTTP status codes are grouped into five categories, each with a specific meaning:

  • (100-199) Informative responses
  • (200-299) Successful responses
  • (300-399) Redirection
  • (400-499) Customer errors
  • (500-599) Server errors

It is important to remember that the list of HTTP status codes is not definitive, and some companies may use their own set of codes. If you find a new, unknown status code, it is important to check with the company what the corresponding code means. For more details, see "List of HTTP status codes" on Wikipedia.

Payload​

Just like a truck transports cargo from one place to another, HTTP requests transport information to an API. Requests that create or update existing records in the API need to load data for the operation. For example, when creating a customer in a sales management system using an API, you must send the customer's information to the API. This information is sent in the request payload, in JSON format or another format defined by the API. The API uses this information to create the new customer record in the sales management system.

URI​

URI is the acronym in English for "Uniform Resource Identifier". It is a sequence of characters that uniquely identifies a resource on the Internet. These resources may be web pages, images, documents, services, among others.

URIs are used in different contexts, such as in web browsers to access pages on the Internet, in REST APIs to identify specific endpoints, and in other applications that need to communicate with resources available on the network. An example of a URI is the URL (Uniform Resource Locator), which is a specific type of URI used to identify the location of a resource on the Internet.

Last updated on