![Banner image](https://cdn-prod.scdn6.secure.raxcdn.com/static/media/341a9822-300f-4509-8d8a-c670f49acece.jpeg?_cb=1674844830.998351)
Getting Started with REST API
Fri, 27 Jan 2023 18:41:52 -0000
|Read Time: 0 minutes
What is REST API?
REST stands for Representational State Transfer, and it is an architectural style for building APIs, or application programming interfaces. JSON stands for JavaScript Object Notation, a lightweight format for storing and transmitting data between a server and a client application. REST and JSON are popular technologies in building web APIs.
.
HTML methods in REST API calls
The server interface for a REST API is organized as resources that can be accessed through a uniform resource identifier (URI) to access resources and perform actions. HTTP methods like GET and PUT perform one of CRUD: CREATE, READ, UPDATE and DELETE operations on the resources.
REST API calls can be used from almost any modern programming language with the following HTTP methods to communicate with the web server:
- GET: the GET method is used to retrieve a resource from the server. It is heavily used for things like loading a dynamic web page. When used programmatically, the output of this method is captured in a variable of the programming language and then parsed to retrieve different components of the output.
- PUT: the PUT method is used to create or update an existing resource on the server. Note that the body of the request should contain the entire object structure of the resource. When the resource doesn’t exist, PUT creates a new resource.
- POST: the POST method is used to create a new resource on the server. The body of a POST request has all the details of the new record and is usually validated on the server side for expected type of data and completeness of the record. Note that the main difference between POST and PUT is that PUT requests are idempotent. That is, calling the same PUT request multiple times will always produce the same result. By contrast, calling a POST request repeatedly creates the same resource multiple times.
- DELETE: the DELETE method is used to delete a resource.
- PATCH: The PATCH method is used to apply partial modifications to a resource. Unlike PUT requests, PATCH requests apply a partial update to the resource.
JSON and the anatomy of a REST API call
In response to the API calls, the web service provides a response in JSON format. JSON is a lightweight, human-readable format for representing structured data. The response includes the status of the call, information requested, and any errors using specific codes. This response is further parsed and processed by the client application.
Here is how a simple GET request looks like when used on a shell CLI with the CURL command:
The JSON response to a call is provided in a <name>:<value> format:
"servers": [ { "id": 123, "name": "alice" }, { "id": 456, "name": "bob" } ] }
JSON supports nested structures, which allow an object or array to contain other objects and arrays. For example, consider the following JSON data:
{ "name": "John Doe", "age": 35, "address": { "street": "123 Main St", "city": "New York", "state": "NY" }, "phoneNumbers": [ { "type": "home", "number": "212-555-1212" }, { "type": "office", "number": "646-555-1212" } ] }
HTTP return codes
In a REST API, HTTP status codes indicate the outcome of an API request. Here are some common HTTP status codes that a REST API might return, along with their meanings and suggestions for how a client application could handle them:
- 200 OK: The request was successful! The response body contains the requested data. The client can continue to process the response as normal.
- 201 Created: The request resulted in the creation of a new resource. The response body may contain the newly created resource; the Location header of the response will contain the URL of the new resource. The client should store this URL for future reference.
- 204 No Content: The request was successful, but the response body is empty. The client should continue processing as normal, but should not try to parse the response body.
- 400 Bad Request: The request was not valid, for example because it contained invalid parameters or was missing required data. The response body may contain more detailed error information. The client should check the error details and adjust the request as needed before trying again.
- 401 Unauthorized: The request requires the client to authenticate itself, but the client did not provide a valid authentication token. The client should prompt the user for their credentials and try the request again with a valid authentication token.
- 404 Not Found: The requested resource does not exist. The client should check that the URL of the request is correct and adjust it if necessary before trying again.
- 500 Internal Server Error: The server encountered an unexpected error while processing the request. The client should try the request again at a later time, because the issue may be temporary.
Client applications must handle these different HTTP status codes properly to provide a good user experience. For example, if a client receives a 404 Not Found error, it could display a message to the user indicating that the requested resource was not found, rather than just displaying an empty screen.
Authentication
There are several popular authentication mechanisms for REST APIs, including:
1. Basic authentication: This simple authentication scheme uses a username and password to authenticate a user. The username and password are typically sent in the request header.
curl -X GET 'https://api.example.com/server' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ='
In this example, the Authorization header is set to Basic dXNlcm5hbWU6cGFzc3dvcmQ=, where dXNlcm5hbWU6cGFzc3dvcmQ= is the base64-encoded representation of the string username:password.
2. Token-based authentication: In this scheme, the client exchanges a username and password for a token. The token is then included in subsequent requests to authenticate the user.
curl -X GET 'https://api.example.com/users' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer abc123'
In this example, the Authorization header is set to Bearer abc123, where abc123 is the token that was issued to the client.
3. OAuth: This open-standard authorization framework provides a way for users to authorize access to APIs securely. OAuth involves a client, a resource server, and an authorization server.
4. OpenID Connect: This is a protocol built on top of OAuth 2.0 that provides a way to authenticate users using a third-party service, such as Google or Facebook.
Resources
The Dell Technologies infrastructure portfolio has extensive APIs covering all IT infrastructure operations. You can learn more about the API implementation of the different Dell infrastructure products on the Info Hub:
- PowerStore REST API: Using Filtering to Fine Tune Your Queries
- REST API examples for PowerMax snapshot operations
- REST - The Power of Network Automation Using REST APIs
- ECS Management REST API: Postman Collection
- VxRail API—Updated List of Useful Public Resources
- What’s New in PowerMax REST API 10.0
You can also explore Dell infrastructure APIs by visiting the API documentation portal: https://developer.dell.com/apis.
Authors: Florian Coulombel and Parasar Kodati