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"

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.

Loading...