To use CIVIL API, it is essential to understand the base URL and API Key.
Before reading this page, I recommend you understand the following document.
baseURL
In REST API, the baseURL represents the default URL of the API endpoint*. It defines the common base address used in all HTTP requests with the API server.
Typically, the baseURL serves as the root address of the API, determining the relative addresses of all endpoints based on this root. For instance, here's an example of a simple REST API:
Base URL: https://api.example.com Endpoints: - /users - /posts - /comments
In this case, the baseURL is https://api.example.com, and the endpoints "/users," "/products," and "/orders" are relative to this baseURL.
Therefore, the endpoint to retrieve user information would be https://api.example.com/users, and the endpoint to retrieve post information would be https://api.example.com/posts.
Using the baseURL, the API client can communicate with the API server without repeating the server address in every request. This helps simplify the code and makes maintenance easier.
*endpoint: The URL path to access a specific resource or service in a REST API.
API Key
The API key is a security string that grants authentication and access permissions to developers or applications using a web API. Our ally provided as a string. It identifies and authenticates the client making API calls. Its key roles include:
- Authentication and Access Control: The API key identifies and authenticates the client sending requests to the API server. The server only accepts and processes requests with the correct API Key.
- User Identification: Identifying which user or application uses the API through the API key is possible. This proves beneficial for logging, analysis, and tracking usage.
- Access Control and Permission Management: API keys help manage the access levels for clients and assign permissions. They enable restrictions or authorizations for different API endpoints or functionalities.
- Security Measures: The API key acts as an additional security layer against attempts to misuse the API. In the case of public APIs, exposure of the API key can prompt server or client-side measures to prevent abuse and unauthorized usage of the API.
The API key is usually included in the HTTP request header or request parameter. For example, the typical way to include an API key in a request is as follows:
Including the API key:
- In the header: Pass the API key in the HTTP request header, often as an Authorization or custom header.
- In the Request Parameter: Include the API key in the URL query string when requesting.
As the API key holds sensitive information, securely storing and transmitting it is crucial. Following guidelines provided by the API service provider regarding the generation and management of API keys is also a good idea.
base URL and API Key of CIVIL API
CIVIL API utilizes both the base URL and an API-Key concept.
The base URL can vary based on product usage, country, or server. You can verify it based on the product path below.
The API-Key, called MAPI-Key in CIVIL API, must be included in the header when requesting REST API responses. Therefore, adding the key “MAPI-Key” to the header with the corresponding product key value is essential to enable functionality. You can verify this based on the product path below, which is similar to the base URL.
Example
Why MAPI-Key can be changed?
MAPI-Key is a crucial parameter identifying the specific MIDAS product connecting to the server. Depending on the user's PC or network environment, assigning a fixed value for each product or user might pose security threats.
The risk lies in the potential remote control of a user's product if the key is compromised. Randomly generated temporary keys can be used as an alternative to the MAPI-Key concept.