This article provides a glossary for a number of common terms that you may come across when using our REST API.
API
API stands for Application Programming Interface, which doesn't really explain much. Think about it like this: An API receives inbound requests and sends outbound responses. You make a request, the API passes that request to a server, and then waits for the server's response. As an application's user interface (UI) lets users interact with it, an application programming interface (API) lets clients interact with the application. It's just another way to interact with a system and its functionality.
REST
REST stands for REpresentational State Transfer. A REST API is one that adheres to six specific architectural constraints that make interacting with them easier and less resource intensive.
For details, see Representational state transfer on Wikipedia.
JSON
The Built Intelligence’s API is a JSON API, meaning it only accepts and returns JSON data.
JSON stands for JavaScript Object Notation, but don't let the JavaScript part throw you off. JSON is not a programming language: it's a human-readable data format. The JSON format can be used to store and transfer information in a standard way.
JSON adheres to a strict syntax. Mind your commas, colons, parentheses, and curly braces ({}). They'll be your best friends and worst enemies.
To highlight just how readable JSON is, here's a syntactically (and factually) correct JSON object that you'll be able to interpret without even knowing anything about JSON yet:
{ "facts": { "name": "Chris", "is_NEC_geek": true }}
To learn more, see Working with JSON.
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 HTTP request methods: GET (read), PUT (update), POST (create), DELETE (delete). 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 when browsing the web. For example, when you use Google search, your web browser makes one GET request after another.
Endpoint
You use endpoints to actually call an API. As the word implies, an endpoint is the location that receives web requests. An API is a collection of endpoints. Each endpoint has its own rules on CRUD operations.
HTTP response status codes
When you make a request to an endpoint, the server:
- Looks at the information sent.
- Looks for the resource referenced in the request.
- Checks if you have permission to access it.
- Returns a response with a status code.
Each status code has a specific meaning. They are grouped together conveniently into the following five groups:
- (100-199) Informational responses
- (200-299) Successful responses
- (300-399) Redirect messages
- (400-499) Client errors (you messed up)
- (500-599) Server errors (the server messed up)
For details, see List of HTTP status codes on Wikipedia. It's not a definitive list and some infrastructure companies like Cloudflare have their own set of status codes. Keep this in mind if you see a strange new status code that you can't find anywhere.
Payload
As a ship carries a payload to a port, some HTTP requests carry a payload to an API. HTTP requests that create records or update existing records also need to carry the data to the API. For example, when creating a user in Built Intelligence with the API, you need to send the user information to the API. The payload contains the new user information (in JSON format) that the API will use to create the user in Built Intelligence.
Comments
0 comments
Please sign in to leave a comment.