API Fundamentals Lab

RESTful APIs

Apstra uses a REST (REpresentational State Transfer) API, which is an architectural style for delivering APIs that is based on the HTTP specification used by the web. It’s important to note that REST is a style, rather than a standard, and it is made up of different components such as HTTP, XML, URL, and JSON.

REST APIs use URLs (uniform resource locators) to make data available, and they rely on HTTP methods, headers, and other building blocks to facilitate communication between systems. One of the benefits of REST APIs is that they are simple and widely recognized, making them a common starting point for teams when they are first learning about APIs. In contrast, SOAP APIs are more structured and formalized, and may require more setup and configuration.

To interact with a resource using a REST API, you need to use a URL to specify the resource you want to access and an HTTP method to indicate the type of request you are making. The four main HTTP methods used in REST APIs are:

GET: The GET method allows you to retrieve an object or data from the server. When you make a GET request, the server sends the requested object back to you in the form of a response.
POST: The POST method tells the server to create a new object. This object may have parameters that need to be specified in the request.
PUT: The PUT method tells the server to update an existing object.
DELETE: The DELETE method tells the server to delete one or more entries from the system.

These HTTP methods correspond to the common CRUD (create, read, update, delete) operations that are often used in computing. By using the appropriate method, you can perform a wide range of actions on resources using a REST API.

API Basic Methods

In the following sections, we will go into more detail about the key components of RESTful API calls, including the HTTP methods HTTP structure, and the parameters that may be included in the request.

HTTP Header and Body

When two systems communicate using a RESTful API, there is a request and response process. The client sends a request to the server, and the server sends a response back to the client. Both the request and the response consist of a HTTP header and a HTTP body. The header contains information about the request or response, such as the type of content being sent and the status of the request. The body contains the actual content being sent, such as data or parameters. By following this request-response process, the client and server can communicate and exchange information using the APIs.

API in human speak

HTTP Headers

HTTP headers are used to send additional information with an HTTP request or response. They can be thought of as "meta-data" for your API calls, as they contain information such as API tokens, caching details, and the type of content being sent in the body of the request or response. By including this information in the header, the client and server can pass along additional details about the request or response, helping to facilitate communication between the two systems.

HTTP Body

The HTTP body is the part of an HTTP request or response that contains the actual content being sent. For example, if you make a POST request to Apstra asking it to create a new VRF, the HTTP body will contain the necessary information about the VRF, such as its name and any other relevant details. In general, the HTTP body is used to include information that is relevant to the API call being made, and it can be in a variety of formats such as text, JSON, or XML.

HTTP Methods

The table below describes five of the common API methods you’ll come across in the Apstra API. This section does omit the HEAD, OPTIONS and TRACE methods, but you can read about these elsewhere.

Idempotency refers to an action or operation that produces the same result regardless of how many times it is performed. In the context of APIs, this means that if you make the same request multiple times, you will receive the same response. For a RESTful service, this means that clients can make repeated calls to the same endpoint without changing the overall result. However, it’s important to note that while the result on the server may be the same, the actual response may not be identical (e.g., a resource’s state may have changed between requests). This is because idempotency only refers to the result of the operation, not the specifics of the response itself. Overall, idempotency is an important concept in API design, as it helps to ensure that operations are predictable and consistent, even if they are repeated multiple times.

HTTP Verb

CRUD

Description

GET

Read

The HTTP GET method is used to retrieve data or a representation of a resource. When you make a GET request, the server sends a response containing the requested data, along with a HTTP response code indicating the status of the request. If the request was successful, the response code will be 200 (OK). If there was an error, the response code may be 404 (NOT FOUND) or 400 (BAD REQUEST).

According to the HTTP specification, GET requests should only be used to read data, and not to change data. This makes GET requests safe, as they can be called without risking data modification or corruption. GET requests are also idempotent, which means that making multiple identical requests has the same effect as making a single request. In other words, calling a GET request once has the same result as calling it multiple times. These properties of GET requests make them useful for retrieving data from a server without altering it in any way.

POST

Create

The POST verb is typically used to create new resources. When you make a POST request, the server processes the request and creates a new resource. If the resource is created successfully, the server will return a HTTP response code of 201, along with a payload containing information about the new resource, such as its ID.

Unlike GET requests, POST requests are not safe or idempotent. This means that making two identical POST requests will likely result in the creation of two separate resources with the same information. This is because POST requests are used to create new resources, rather than simply reading or retrieving existing ones. As a result, POST requests can have unintended consequences if they are repeated, and they should be used with caution.

PUT

Update/Replace

The PUT verb is typically used to update existing resources. When you make a PUT request, you send a new representation of the resource, containing updated information. This means that while you are not creating a new resource, you are overwriting the existing information about it.

If a PUT request is successful, the server will return a HTTP response code of 200 (OK) or 204 (No Content). PUT requests are not safe, because they modify the state of a resource on the server. However, they are idempotent, which means that making multiple identical PUT requests has the same effect as making a single request. In other words, if you update a resource using PUT and then make the same request again, the resource will still exist and will have the same state as it did after the first request. This makes PUT requests useful for updating resources without affecting their overall state.

PATCH

Update/Modify

The PATCH verb is used to modify existing resources. When you make a PATCH request, you only need to send the changes that you want to make to the resource, rather than the complete resource itself. This allows you to make specific updates to a resource, rather than replacing it in its entirety. PATCH requests are typically used to make partial updates to a resource, rather than replacing it completely like a PUT request would. The server will process the request and apply the specified changes to the resource, and may return a response indicating the status of the request.

DELETE

Delete

The DELETE verb is used to delete a resource from the server. When you make a DELETE request, the server processes the request and removes the resource from the server. If the request is successful, the server will return a HTTP response code of 200 (OK) along with a response body, or a code of 204 (No Content) with no response body.

DELETE operations are typically idempotent, which means that making multiple identical DELETE requests has the same effect as making a single request. In other words, if you delete a resource using DELETE and then make the same request again, the resource will still be gone. However, it’s worth noting that the response code for the first DELETE operation may be different from subsequent operations. Overall, DELETE is a straightforward and easy-to-understand verb that is used to remove resources from the server.

Status Codes

HTTP response status codes are used to indicate the status of an HTTP request. They provide information about whether the request was successful or not, and if not, they give some insight into what went wrong. There are five main categories of HTTP status codes:

1xx Informational responses

These codes indicate that the request was received and is being processed.

2xx Successful responses

These codes indicate that the request was received, understood, and accepted.

3xx Redirection responses

These codes indicate that further action is required to complete the request.

4xx Client error responses

These codes indicate that there is a problem with the request, such as bad syntax or an inability to fulfill it.

5xx Server error responses

These codes indicate that the server failed to fulfill an apparently valid request.

Understanding HTTP response status codes is important for understanding the results of API requests and determining how to handle any errors that may occur.

All HTTP status codes are well documented so when in doubt, Google!

The table below shows some of the most common HTTP status codes you are likely to come across.

CODE

TYPE

Description

200

General success status code. This is the most common response code. Used to indicate success.

201

CREATED

If a POST or PUT request is successful, it means that a new resource has been created or an existing resource has been updated. The server should return a HTTP response code of 201 (Created) and may include a Location header with a link to the newly-created resource. The response body may or may not contain additional information about the resource.

204

NO CONTENT

The HTTP response code 204 (No Content) indicates a successful request with no additional information to provide in the response body. This status code is often used in DELETE and PUT operations. It does not indicate an error.

400

BAD REQUEST

General error for when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc. are some examples.

401

UNAUTHORIZED

Error code response for missing or invalid authentication token.

403

FORBIDDEN

Error code for when the user is not authorized to perform the operation or the resource is unavailable for some reason (e.g. time constraints, etc.).

404

NOT FOUND

Used when the requested resource is not found, whether it doesn’t exist or if there was a 401 or 403 that, for security reasons, the service wants to mask.

500

INTERNAL SERVER ERROR

Never returned intentionally. The general catch-all error is when the server-side throws an exception. Use this only for errors that the consumer cannot address from their end.