The API has some strengths, such as clearly marking required parameters and providing endpoint descriptions. But lacks some parameters to enable more granular requests, and would gain to have shorter descriptions.
Main areas of improvements
Parameter Descriptions
The parameters should have detailed descriptions, including the format and scope.
Operation IDs
Including an operationId for each endpoint would help in identifying operations uniquely.
Numerous parameters
More parameters are useful to allow the LLM to make more focused requests, based on the users' query.
Details of the rating criteria
CRITERIA
DESCRIPTION
SCORE
BLOBR COMMENT
Required Parameters
Documentation must include the required parameters.
12
12
/15
Some endpoints clearly specify required parameters, but not all.
Numerous and described endpoints
For each endpoint, the parameters for filtering information must be numerous and include descriptions.
7
7
/10
Some endpoints could have more parameters, to enable more granular requests.
Operation IDs
Documentation must include operation IDs.
3
3
/5
20 out of 39 endpoints have Operation Ids
Endpoint Descriptions
Documentation must include a clear and unambiguous description of each endpoint and data point.
12
12
/15
Endpoints all feature descriptions, some might lack clarity and be too long.
Data Model Clarity
Data model must be clear so that it can be used to make multiple calls from different endpoints.
8
8
/10
Some endpoints clearly specify required parameters, but not all.
Use Cases
The use cases that can be created must be obvious.
9
9
/10
The API features numerous descriptions, tags, and complete responses making it easy to identify use cases.
Analytics Endpoints
Analytics endpoint must be available to answer analytics-related questions.
0
0
/10
There's no dedicated analytics endpoint or functionality in the API.
Heaviness of Data Payload
Data payload and answers should not be too heavy, to avoid hallucinations.
8
8
/10
Payload can be limited to enable the LLM to process the data better. The default 100 items per page may be too heavy to handle, if the prompt doesn’t specify the need to ask for leaner pages.
Authentication Description
The API support authentication mechanisms, to ensure that the LLM can access the data it needs while maintaining security.
5
5
/5
The API uses an OAuth authentication mechanism, ensuring secured access.
Pagination
Data payload must be paginated and detailed in the specifications.
5
5
/5
Pagination is present, limiting the payload.
Check the AI-compatibility of your API
Share your API specifications and get a free report on how to leverage AI with your API.
