Overview

A REST API serves as a bridge between applications, enabling them to exchange information through standard web requests. When one application needs data from another, it sends a request to the REST API using a specific URL that defines the required data. The API then responds with the requested information in a format such as JSON, which is easy for applications to interpret.

Each element of a REST API request plays a distinct role: the URL specifies the data or action requested, HTTP methods (such as GET, POST, PUT, and DELETE) define the type of operation (like retrieving or updating data), and parameters can refine the request (such as by specifying a particular timeframe). Status codes, such as 200 for success or 404 for not found, inform the application whether the request succeeded or encountered an issue.

This structure makes REST APIs very flexible and easy to use, allowing applications to request and share data efficiently, regardless of the underlying technology.

Parameters & Responses

REST API requests often include parameters and return structured responses. Parameters refine the data or behavior of the API request, and responses return data in a standardized format, usually JSON, to inform the client of the outcome.

Parameters

• Path Parameters: Placed within the endpoint URL to specify a particular resource (e.g., /api/users/{userId}).

• Query Parameters: Appended to the URL after a ? symbol to filter or sort data (e.g., /api/users?role=admin).

• Header Parameters: Included in the request headers to pass metadata like authorization tokens or content types.

• Body Parameters: Primarily used in POST or PUT requests to send data in JSON format within the body of the request.

Responses: Responses contain the outcome of a request in JSON format, often including metadata like timestamps, resource IDs, or pagination data.

Status Codes

Status codes in REST APIs are HTTP responses that indicate the result of an API request. They help clients understand whether a request was successful or if an error occurred, allowing for better error handling and user feedback.

Common HTTP Status Codes

• 200 OK: The request was successful, and the server returned the requested data.

• 201 Created: The server successfully created a new resource (usually used with POST requests).

• 204 No Content: The request was successful, but no data is returned (often used with DELETE).

• 400 Bad Request: The server could not understand the request due to invalid syntax.

• 401 Unauthorized: The client must authenticate itself to get the requested response.

• 403 Forbidden: The client does not have permission to access the requested resource.

• 404 Not Found: The server could not find the requested resource.

• 500 Internal Server Error: The server encountered an error and could not complete the request.

Understanding these status codes is essential for troubleshooting and creating effective error-handling mechanisms in applications that consume REST APIs.

URLs

Our API URLs are built semantically to make it easy to understand the functionality made available.

Example URLs

• Get the planned power for plant plant “PLANT_1” from 1.1.2025 12:00 to 2.1.2025 12:00:
  https://api.hydrogrid.ai/v1/plant/PLANT_1/power/active-gross-plan?start-ts=1735732800000&end-ts=1735819200000
  
  

• Get inflow plan for all reservoirs in plant “PLANT_1” from 1.1.2025 12:00 to 2.1.2025 12:00:
  https://api.hydrogrid.ai/v1/plant/PLANT_1/reservoir/inflow-plan?start-ts=1735732800000&end-ts=1735819200000
  
  

• Submit reservoir level timeseries for a reservoir in plant “PLANT_1”:
  https://api.hydrogrid.ai/v1/plant/PLANT_1/reservoir/level
  (and a body in JSON form which contains the reservoir level readings)