REST API
Compatibility guidelines
The HTTP API is versioned with a single number, which is 1
. This number symbolizes the major version number, as described by SemVer. Because of this, backward-incompatible changes require this version number to change.
The minor version isn't explicit, which allows for a stable API endpoint. New features can be added to the API in the same version number.
All deprecations and changes between versions are in the documentation.
Current status
Only API version v1 is available.
How to use the API
API requests must include both api
and the API version.
For example, the root of the v1 API is at /api/v1
.
Valid API request
The following is a basic example of a request:
curl "https://secdb.nttzen.cloud/api/v1/version"
API request to expose HTTP response headers
If you want to expose HTTP response headers, use the --include
option:
curl --include "https://secdb.nttzen.cloud/api/v1/version"
HTTP/1.1 200 OK
...
This request can help you investigate an unexpected response.
API request that includes the exit code
If you want to expose the HTTP exit code, include the --fail
option:
curl --fail "https://secdb.nttzen.cloud/api/v1/does-not-exist"
curl: (22) The requested URL returned error: 404
The HTTP exit code can help you diagnose the success or failure of your REST request.
Status codes
The API is designed to return different status codes according to context and action. This way, if a request results in an error, you can get insight into what went wrong.
The following table gives an overview of how the API functions generally behave.
Request type | Description |
---|---|
GET |
Access one or more resources and return the result as JSON. |
POST |
Return 201 Created if the resource is successfully created and return the newly created resource as JSON. |
GET / PUT |
Return 200 OK if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
DELETE |
Returns 204 No Content if the resource was deleted successfully or 202 Accepted if the resource is scheduled to be deleted. |
The following table shows the possible return codes for API requests.
Return values | Description |
---|---|
200 OK |
The GET , PUT or DELETE request was successful, and the resource itself is returned as JSON. |
201 Created |
The POST request was successful, and the resource is returned as JSON. |
202 Accepted |
The GET , PUT or DELETE request was successful, and the resource is scheduled for processing. |
204 No Content |
The server has successfully fulfilled the request, and there is no additional content to send in the response payload body. |
301 Moved Permanently |
The resource has been definitively moved to the URL given by the Location headers. |
304 Not Modified |
The resource hasn't been modified since the last request. |
400 Bad Request |
A required attribute of the API request is missing. For example, the title of an issue is not given. |
401 Unauthorized |
The user isn't authenticated. A valid user token is necessary. |
403 Forbidden |
The request isn't allowed. For example, the user isn't allowed to delete a project. |
404 Not Found |
A resource couldn't be accessed. For example, an ID for a resource couldn't be found, or the user isn't authorized to access the resource. |
405 Method Not Allowed |
The request isn't supported. |
409 Conflict |
A conflicting resource already exists. For example, creating a project with a name that already exists. |
412 Precondition Failed |
The request was denied. This can happen if the If-Unmodified-Since header is provided when trying to delete a resource, which was modified in between. |
422 Unprocessable |
The entity couldn't be processed. |
429 Too Many Requests |
The user exceeded the application rate limits |
500 Server Error |
While handling the request, something went wrong on the server. |
503 Service Unavailable |
The server cannot handle the request because the server is temporarily overloaded. |
Pagination
Sometimes, the returned result spans many pages. When listing resources, you can pass the following parameters:
Parameter | Description |
---|---|
page |
Page number (default: 1 ). |
limit |
Number of items to list per page (default: 100 , max: 1000 ). |
In the following example, we list 50 CVE per page:
curl --request GET "https://secdb.nttzen.cloud/api/v1/feed/cve?limit=50"
Pagination Link header
Link
headers are returned with each response. They have rel
set to prev
, next
, first
, or last
and contain the relevant URL. Be sure to use these links instead of generating your own URLs.
In the following cURL example, we limit the output to 50 items per page (limit=50
) and we request the second page (page=2
):
curl --head "https://secdb.nttzen.cloud/api/v1/feed/cve?limit=50&page=2"
The response is:
HTTP/1.1 200 OK
[...]
Link: </api/v1/feed/cve?limit=50&page=1>; rel="prev", </api/v1/feed/cve?page=1>; rel="first", </api/v1/feed/cve?limit=50&page=5114>; rel="last", </api/v1/feed/cve?limit=50&page=3>; rel="next"
X-Next-Page: 3
X-Page: 2
X-Per-Page: 50
X-Prev-Page: 1
X-Total: 255709
X-Total-Pages: 5114
Other pagination headers
SecDB also returns the following additional pagination headers:
Header | Description |
---|---|
x-next-page |
The index of the next page. |
x-page |
The index of the current page (starting at 1). |
x-per-page |
The number of items per page. |
x-prev-page |
The index of the previous page. |
x-total |
The total number of items. |
x-total-pages |
The total number of pages. |
Data validation and error reporting
When working with the API you may encounter validation errors, in which case the API returns an HTTP 400
error.
Such errors appear in the following cases:
- A required attribute of the API request is missing
- An attribute did not pass the validation
When an attribute is missing, you receive something like:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"message": "Missing required value",
"path": "/"
}
],
"status": 400
}
When a validation error occurs, error messages are different. They hold all details of validation errors:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors": [
{
"message": "Invalid value",
"path": "/"
}
],
"status": 400
}
This makes error messages more machine-readable. The format can be described as follows:
{
"errors": [
{
"message": "<error-message>",
"path": "<error-path>"
},
{ ... }
],
"status": <status-code>
}
Unknown route
When you attempt to access an API URL that doesn't exist, you receive a 404 Not Found message.
HTTP/1.1 404 Not Found
Content-Type: application/json
{
"errors": [
{
"message": "Not Found.",
"path": "/"
}
],
"status": 404
}
Rate Limits
RateLimit
headers are returned with each response.
Header | Description |
---|---|
x-ratelimit-limit |
The number of allowed requests in the current period. |
x-ratelimit-remaining |
The number of remaining requests in the current period. |
x-ratelimit-reset |
The number of seconds left in the current period. |
x-ratelimit-used |
The number of requests in the current period. |
When the user exceeded the application rate limits, SecDB return 429 Too Many Requests
response.