API Basics for Beginners: Understanding the Fundamentals

An API (Application Programming Interface) is a set of rules and protocols that enables two different systems or software to communicate with each other. APIs are used to allow third-party developers to access a company's data and services, and to allow different systems within an organization to communicate with each other.

APIs consist of a set of endpoints that developers can call upon to access specific data or functionality. Each endpoint is a unique URL that represents a specific resource or piece of functionality, and developers can use these endpoints to retrieve or manipulate data.

APIs can be implemented using various protocols such as REST, SOAP, and GraphQL. They are used to access web-based services, databases, and other resources. APIs are widely used in web development and mobile app development, they allow the integration of different services, and data across different platforms.

APIs are also used to authenticate and authorize access to a service or resource, and to ensure that only authorized users can access the data. This is important for security and privacy.

Widely used APIs

REST (Representational State Transfer) is a popular architectural style for building web services. RESTful APIs use HTTP requests to POST (create), PUT (update), GET (read), and DELETE data. RESTful APIs are typically easier for developers to use and understand, and they are often used to build web and mobile applications. RESTful APIs are also more flexible, and can handle a wide variety of data formats, including JSON and XML.

SOAP (Simple Object Access Protocol) is a protocol for exchanging structured data between applications over the internet. SOAP uses XML as its message format, and can be carried over a variety of lower-level protocols, including HTTP and SMTP. SOAP is typically used in enterprise environments for building web services, and it includes built-in error handling. SOAP is also more strict and requires more overhead to implement compared to REST.

In summary, REST is a popular architectural style for building web services that uses HTTP requests to manipulate data and is often used for web and mobile development. SOAP is a protocol for exchanging structured data between applications that uses XML as its message format, typically used in enterprise environments for building web services and includes built-in error handling.

Components of an API

An API typically consists of the following elements:

Endpoint: This is a unique URL that represents a specific resource or piece of functionality that developers can call upon to access data or functionality.
Method: This is the type of request (such as GET, POST, PUT, DELETE) that a developer can make to an endpoint to access or manipulate data.
Header: This contains metadata about the request, such as authentication information, the type of content being sent, and other details that can be used by the API to process the request.
Body: This contains the data that is sent in the request or received in the response.
Parameters: These are additional pieces of information that can be included in the request to specify how the data should be processed or returned.
Status Code: This is a numerical code that is returned in the response to indicate the outcome of the request, such as 200 for success or 400 for a bad request.
Authentication and Authorization: This ensures that only authorized users can access the data or functionality provided by the API, typically through the use of API keys or OAuth tokens.
Error handling: This defines how the API handles errors that occur, such as invalid requests or missing data.
Rate limiting: This limits the number of requests that can be made to the API within a certain time period, to prevent overuse and protect the system from being overwhelmed.
Versioning: This allows for changes to be made to the API without breaking existing applications that rely on it, by versioning the API and maintaining backward compatibility.
Documentation: This is a set of instructions that explain how to use the API, including the available endpoints, methods, and any required parameters.

Types of API Request

API requests are used to retrieve or manipulate data from a server. The four most common types of API requests are GET, POST, PUT, and DELETE.

GET: This request is used to retrieve data from the server. It is the most common type of request and is used to retrieve information about a resource, such as a list of users or a specific user's information.
POST: This request is used to send data to the server to create a new resource. For example, a POST request can be used to create a new user account or to upload a file.
PUT: This request is used to update an existing resource on the server. For example, a PUT request can be used to update a user's information or to replace a file.
PATCH: This request is similar to PUT, but it is used to update only specific fields of a resource, rather than replacing the entire resource.
DELETE: This request is used to delete a resource from the server. For example, a DELETE request can be used to delete a user account or a file.

It's important to note that the availability and usage of these requests may depend on the API that you're using, some APIs may not support all of them. Additionally, the names for these requests may be different depending on the API or framework being used.

Status Code

Status codes are three-digit numbers returned by servers to indicate the status of a client's request. These codes are used to communicate whether a request was successful, as well as to provide additional information about the request.

The most common status codes include:

200 OK: Indicates that the request was successful and the requested information has been returned.
201 Created: Indicates that the request was successful and a new resource has been created as a result.
204 No Content: Indicates that the request was successful, but there is no information to return.
400 Bad Request: Indicates that the request was malformed or invalid.
401 Unauthorized: Indicates that the request requires authentication.
403 Forbidden: Indicates that the client does not have permission to access the requested resource.
404 Not Found: Indicates that the requested resource could not be found.
500 Internal Server Error: This indicates that an error occurred on the server while processing the request.

These are just a few examples of the many HTTP status codes that exist. Each status code provides specific information about the outcome of a request and can be used by client-side applications to handle the response appropriately.

How APIs are made on the backend

An API, or application programming interface, can be created using many different programming languages. The basic concept of an API remains the same regardless of the language used to build it.

Routes define the URL structure of the API and specify how clients can access the resources and data provided by the API.
Controllers handle the logic and functionality of the API, such as processing requests, performing actions, and returning responses.
Models define the structure and format of the data that is used by the API, as well as any validation and business logic that is used to process and manipulate the data.

Overall, these three concepts work together to create a functional and efficient API. The route defines the path for clients to access the data, the controller defines the actions that can be performed on that data, and the model defines the structure and format of that data.

Security of API

HTTPS

Always choose HTTPS. That is achieved by using SSL (Secure Sockets Layer). Its installation establishes authenticated and encrypted connections between the browser and the client. You can imagine it as turning the request and response pigeons into eagles so nobody can know that they are postal pigeons while on delivery.
Password hash

Always hash all passwords. You can imagine it as a key owned by students who want to unlock the knowledge that the pigeons deliver from the librarians. However, the key is magical and scrambled into a spoon so that nobody knows it is a key.
API key in URL- NEVER!

If you are using an API key, never expose it on the URL. This applies to any passwords, usernames, and session tokens as well. Neither of them should be displayed in the parameters of the API. And when speaking about an API key, those are used between applications for recognizing each other (teachers will send API keys to librarians when sending the request pigeon for info; good practice is to include the API key in headers or body). For example, your favorite takeout food application includes google maps in it with an API key.
OAuth

When possible, use OAuth (Open Authorization). This is a standard for the authorization of resources. OAuth is used to authorize and authenticate the users while the API key is used to authenticate and use the applications. This is how librarians and teachers can find out if students are authorized to have access to the knowledge. OAuth makes it possible for users to sign into one application/platform and then view data or perform actions in another platform, for example signing into other applications with your Facebook profile.
Timestamp and parameter validation

Adding a timestamp to the request headers is a great way to provide security. The server will be able to control whether the request was sent within a reasonable timeframe (1–2min). You can also include parameter validation. If there are strong validation checks on the first step, the request can be rejected as soon as the validation fails.