REpresentational State Transfer
REST stands for Representational State Transfer. It is an architectural style used in web development to design networked applications. RESTful APIs (Application Programming Interfaces) are built based on the principles of REST.
A REST API is a set of rules and conventions that enable different software applications to communicate with each other over the internet. It provides a standardized way of accessing and manipulating resources (data or functionality) on a server using the HTTP protocol.
Here are some key characteristics of a REST API:
- Statelessness: The server does not store any client state. Each request from the client must contain all the necessary information to understand and process it.
- Client-Server Architecture: The client and server are separate entities that communicate over the network. The client is responsible for the user interface and user experience, while the server handles data storage and processing.
- Uniform Interface: REST APIs have a uniform and consistent interface, typically using HTTP methods such as GET, POST, PUT, DELETE, etc., to perform different operations on resources. Each resource is identified by a unique URL (Uniform Resource Locator).
- Resource-Oriented: Resources are the key concept in REST. Each resource is uniquely addressable and can be represented in various formats like JSON, XML, or others.
- Stateless Communication: Each request from the client to the server is self-contained and does not rely on any previous requests. The server treats each request as an independent transaction.
- Cacheability: Responses from the server can be cached by the client or intermediary servers to improve performance and reduce the load on the server.
CRUD OPERATIONS
In the context of REST API, CRUD stands for Create, Read, Update, and Delete. These are the basic operations that can be performed on resources using HTTP methods. Here's how CRUD operations map to HTTP methods in REST:
- Create (POST): The POST method is used to create a new resource on the server. When you send a POST request to the API endpoint, you include the data for the new resource in the request body. The server then processes the request and creates the resource.
- Read (GET): The GET method is used to retrieve a representation of a resource or a collection of resources from the server. By sending a GET request to the API endpoint, you can retrieve the desired data. You can also specify parameters in the URL to filter or sort the results.
- Update (PUT or PATCH): The PUT or PATCH methods are used to update an existing resource on the server. With a PUT request, you send the entire updated resource representation in the request body, replacing the existing resource entirely. On the other hand, a PATCH request allows you to send only the changes or updates to the resource.
- Delete (DELETE): The DELETE method is used to remove a resource from the server. When you send a DELETE request to the API endpoint, the server identifies and deletes the specified resource./li>
REQUEST OBJECT
In REST API, there are several request objects used to communicate information between the client and the server. The specific request objects used may vary depending on the framework or programming language you are working with, but here are the commonly used request objects in REST APIs:
- HTTP Methods: The HTTP protocol defines various methods that represent different types of requests.
- URL (Uniform Resource Locator): The URL specifies the address of the resource or collection of resources you want to interact with. It usually includes the domain name, path, and query parameters.
- Request Headers: Headers provide additional information about the request or the client. Common
headers used in REST API requests include:
- Content-Type: Specifies the format of the data sent in the request body (e.g., JSON, XML, form data)
- Authorization: Used to authenticate and authorize the client's access to the requested resource
- Accept: Informs the server about the preferred response format (e.g., JSON, XML)
- Request Body: The request body contains the data that is sent to the server for operations like creating or updating a resource. The format of the data in the body depends on the Content-Type header specified in the request.
- Query Parameters: Query parameters are used to filter, sort, or modify the result set when making a GET request. They are appended to the URL after a "?" symbol and are separated by "&". For example: https://api.example.com/products?category=electronics&sort=price.
Request Example :
Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /address/v1/validateEmail
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
"email": "help@example.com",
"validators": [ "SyntaxValidator", "MXValidator", "ListDetectiveValidator" ]
}
RESPONSE OBJECT
In REST API, the server responds to client requests with a response object that contains the data and metadata related to the request. The specific structure and contents of the response object may vary depending on the API implementation, but here are the commonly used components of a response object in REST APIs:
- HTTP Status Code: The HTTP status code indicates the outcome of the request. Some common status
codes include:
- 200 OK: The request was successful, and the server returns the requested data.
- 201 Created: The request to create a new resource was successful.
- 400 Bad Request: The server cannot process the request due to client error.
- 404 Not Found: The requested resource does not exist on the server.
- 500 Internal Server Error: An unexpected error occurred on the server.
- Response Headers: Headers provide additional metadata about the response. They can include information like content type, caching directives, and authentication-related headers.
- Response Body: The response body contains the data returned by the server in response to the request. The format of the data depends on the API and the specific endpoint being accessed. It can be in formats such as JSON, XML, HTML, or plain text.
- Error Messages: In case of errors or exceptions, the response object may include error messages or error codes to help identify the issue. This can assist clients in understanding and handling errors gracefully.
- Pagination Information: If the API returns a large collection of resources, the response may include pagination information. This typically includes details like the total number of resources available, the number of resources returned in the current response, and links or tokens for navigating to the next or previous page of results.
Response Example :
{
"count": 3,
"page": 1,
"pageSize": 50,
"links": {},
"items": [
{
"id": 516016,
"description": "The root folder for assets",
"enterpriseId": 1447640,
"memberId": 1447640,
"name": "Content Builder",
"parentId": 0,
"categoryType": "asset"
},
{
"id": 858661,
"description": "",
"enterpriseId": 1447640,
"memberId": 1447640,
"name": "Event Notification App",
"parentId": 516016,
"categoryType": "asset"
},
{
"id": 932486,
"description": "",
"enterpriseId": 1447640,
"memberId": 1447640,
"name": "TrailheaDX",
"parentId": 516016,
"categoryType": "asset"
}
]
}
Marketing Cloud REST API
The REST API uses JSON request and response bodies and resource endpoints to support multi-channel use. All new Marketing Cloud technologies implement REST API. REST calls are synchronous, with timeout values of 120 for non-tracking operations and 300 seconds for tracking and data retrieve operations. The maximum payload of any call is four megabytes.
To leverage Marketing Cloud and integrate it into your system, you typically need to create an install package. Marketing Cloud is a cloud-based platform that provides various marketing and communication tools.
To learn how to create install package click here
If you want check Marketing Cloud REST API v1 reference click here
Review the permission ID, the path to the permission in Marketing Cloud, and the Installed Packages scope for each REST API resource. Click here
REST API Example :
<script runat="server" language="javascript">
Platform.Load("core", "1");
var MemberID = Platform.Recipient.GetAttributeValue('memberid');
var ClientId = get_config[0]["Client_ID"];
var ClientSecret= get_config[0]["Client_Secret"];
var url = 'domain/v2/token';
var ContentType = 'application/json';
var payload = {
"client_id": ClientId,
"client_secret": ClientSecret,
"grant_type": "client_credentials"
};
try{
var accessTokenResult = HTTP.Post(url, ContentType, Stringify(payload));
var statusCode = accessTokenResult["StatusCode"];
var response = accessTokenResult["Response"][0];
var accessToken = Platform.Function.ParseJSON(response).access_token;
Variable.SetValue("@accessToken",accessToken);
}
catch(e)
{
Write(e.message);
}
</script>
Comments
Post a Comment