Overview

This article provides an overview of the structure of REST API requests and responses in VIDIZMO, helping you understand the key components and how to use them effectively. A typical REST API request and response consist of five main components: 


  • Request URI
  • Request Header
  • Request Body
  • Response Header
  • Response Body


Request URI

The Request URI is a key part of the HTTP request. However, in most programming languages and frameworks, it is typically handled separately from the request headers. While the URI is essential to define the resource being accessed, it is usually specified apart from the headers when making a request. This distinction helps ensure that the URI and headers are managed and processed independently, allowing greater flexibility in how requests are structured and sent.


The request URI consists of the following components: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}.


URI scheme:  This specifies the protocol that is used to send the request. For example, http or https.

URI host: Defines the server's domain name where the VIDIZMO REST service endpoint is hosted. This is your VIDIZMO portal's domain URL.

Resource path: : Identifies the resource, often with multiple segments, used by the service to determine the requested operation. For example: user/forgot-password/[email protected] can be used to generate an email to reset password against the specified email-address.

Query string (optional): Provides additional simple parameters, such as selection criteria for the VIDIZMO resource.


Request Header

The Request Header contains the following elements: 


  • HTTP Method: The HTTP method, also known as the operation or verb, is part of the HTTP request line and defines the action to be performed on the resource. Common methods supported by VIDIZMO REST services include:
    • GET – Retrieve data
    • POST – Create or submit data
    • PUT – Update data
    • DELETE – Remove data
  • Optional Header Fields: These are additional fields required by the specified URI and HTTP method. For instance, APIs that require authentication may include an Authorization header, which contains a bearer token to authenticate the request. 


Request Body


The Request Body is typically optional and is included to provide additional data for the HTTP operation or to support the resource specified in the URI. For example:

  • POST operations may include MIME-encoded objects as part of the request body, which are used to pass complex parameters or data.
  • PUT operations, similar to POST, can also include data in the body to update existing resources.


When using POST or PUT methods, it is important to specify the Content-Type header to indicate the format of the body content. VIDIZMO REST API services recommend using the application/json MIME type, which is commonly used for JSON-encoded data.


Response Header

The Response Header includes: 

  • HTTP status code: Indicates the outcome of the request. Common status codes include:
  • 2xx for success (e.g., 200 OK)
  • 4xx for client errors (e.g., 400 Bad Request)
  • 5xx for server errors (e.g., 500 Internal Server Error)

 As indicated in the API documentation.

  • Additional Headers (optional): Other headers may provide additional information about the response, such as Content-Type for the response body format.


Response Body

The Response Body is optional and contains data returned by the server as part of the HTTP response. When included, it typically consists of MIME-encoded objects that provide the requested information or the result of the operation. For example:

  • A GET request for video details in a VIDIZMO Portal may return structured data about the video.
  • The response data is commonly formatted as JSON or XML, as specified by the Content-Type response header.


For example, when you request a user profile from VIDIZMO, it is returned in the response body as the BasicInfo element, one of several name/value paired objects in a data collection (UserProfile Object). In this example, a response header of Content-Type: application/json is also included.