APIFIRST API is a simple way to query FIRST database in order to build web apps or integrate to other CSIRT databases. It currently doesn't support authentication, so only public information is available. One sample application is the Members around the world map.
This documentation refers to the FIRST API, which endpoint URL is be located at: https://api.first.org/data/v1.
The queries at FIRST APIs should follow this URL scheme:
[Endpoint URL][method][.format]?[parameters]The Endpoint URL contains the collection and the version of the API under the endpoint. Current endpoints URL is:
| Repository (sourcename) | Endpoint URL | Status |
|---|---|---|
| FIRST API v1 | https://api.first.org/data/v1 | Stable |
In order to query FIRST API, use the following URL pattern:
https://api.first.org/data/v1[method][.format]?[parameters]The available methods and parameters are described in this document.
Each method is an available dataset, like Teams, Countries, Events and so on. The URLs listed in this document are prefixed by the HTTP method required to use them, followed by the method address relative to the Endpoint URL. Take for example the teams listing, which uses the address GET /teams. It must be read as a GET request to the [Endpoint URL]/teams — to query FIRST API you should then use curl -X GET https://api.first.org/data/v1/teams.
The .format is optional, it's the content type expected for the response. The default output format is application/json. Additional formats (see table) are supported when properly requested. The output format should be requested either as a Accept: header or as an extension to the requested URL. These are the additional formats supported:
| HTTP Accept | Extension | Format |
|---|---|---|
| application/json | .json (default) | JSON. This will be the format used if no extension or Accept: header is provided. |
| application/yaml | .yml | YAML, a more human-readable format. Applications should use two spaces as indentation and maximum column width of 80 characters. |
| application/xml | .xml | XML. Should not contain namespaces and different encodings. |
| application/csv | .csv | Comma-separated values. The first line contains the column names. |
| application/xls | .xls | Microsoft Excel format (legacy). |
| application/xlsx | .xlsx | Microsoft Excel 2007 and Excel 97/2000/XP/2003 binary file. |
Please note: the API uses UTF8 as its encoding. This means that when importing this information in other applications, like spreadsheet applications, you must set the encoding to UTF8 (or Unicode if this one is missing).
The result will also be compressed with Gzip if the request header Accept-Encoding: compress, gzip is present.
The parameters are also optional, they are used to filter and change the scope of the displayed data.
Parameters must be keypair values assigned with an = (equal sign): key=value. The values must be URL encoded (RFC 3986), and multiple parameters must be separated by & (ampersand sign). As an example, param1=foo%20bar¶m2=bar translates into:
foo barbarPublic endpoints without authentication are limited to 1000 requests per minute. Abusive behavior might be temporarily blocked to all API endpoints without further notice. In the event you receive the response 429 Too many requests you have exceeded this limit and have been temporarily blocked.
When looping through large datasets to fetch all records, please consider an appropriate limit to reduce the number of requests sent and avoid concurrent requests.
If you are a FIRST Member and require increased limits, please reach out the infrastructure team using the Support Portal explaining your requirements.
There are some parameters that are reserved for pagination and output control. These parameters are eligible for several methods and should not be used for a method-specific purpose.
| Parameter | Type | Description |
|---|---|---|
| fields | string | Comma-separated list of fieldnames to be retrieved. Used only for limiting the available resultset. |
| limit | integer | Limits the maximun number of records to be shown. Should be an integer number between 0 and 10,000. |
| offset | integer | Offsets the list of records by this number. The first item is 0. |
| sort | string | Comma-separated list of fieldnames to be used to sort the resultset. Fields starting with - (minus sign) indicate a descending order. Each application should define its default sorting options. |
| envelope | boolean | Use true, false, 0 or 1. If set to true will add an object wrapping the resultset, with details on the status, total records found, offset and limit. When false this information is returned at the response header. Defaults to true. |
| pretty | boolean | Use true, false, 0 or 1. If the result should be pretty-printed or no. Defaults to false. |
| callback | string | Only for JSONP resultsets, adds the callback as a function call. Only alphanumerical characters are allowed. |
| scope | string | Collection of fieldnames to retrieve. Affects the resultset and the possible options for the parameter fields. Each data model can specify multiple available scopes. |
The response structure is uniform, it first shows the status and length of the data, and then the data itself.
curl -i "https://api.first.org/data/v1/teams?country=br&scope=country&fields=team&pretty=true"
HTTP/1.1 200 OK
Date: Fri, 22 Jul 2016 21:07:55 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 394
Last-Modified: Thu, 21 Jul 2016 19:02:52 GMT
{
"status": 200,
"status-code": "OK",
"version": "1",
"last-modified": "Thu, 21 Jul 2016 19:02:52 GMT",
"total-count": 4,
"access": "public",
"data": [
{
"team": "Axur"
},
{
"team": "CAIS/RNP"
},
{
"team": "CERT.br"
},
{
"team": "Defenda CERT"
}
]
}The response status can be ommitted from the response body, and be properly set at the response headers with the envelope=false parameter:
curl -i "https://api.first.org/data/v1/teams?country=br&scope=country&fields=team&envelope=false&pretty=true"
HTTP/1.1 200 OK
Date: Fri, 22 Jul 2016 21:30:55 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 162
Last-Modified: Thu, 21 Jul 2016 19:02:52 GMT
X-Status: OK
X-Status-Code: 200
X-Version: 1
X-Total: 4
X-Access: public
[
{
"team": "Axur"
},
{
"team": "CAIS/RNP"
},
{
"team": "CERT.br"
},
{
"team": "Defenda CERT"
}
]The [Response body].status and [Response body].status-code correspond to the HTTP status message. When errors occur, the status code should be different than 2XX. Additionally, a [Response body].message or X-Message header may provide additional information about the error.
The Last-Modified is always present at the response header, it will refer to the last time the resultset that corresponds to this URL was modified. This information can be used for caching (browsers would request the If-Modified-Since header to check if it was modified).
The [Response body].version or X-Version header points out the actual API version used.
The [Response body].total or X-Total header indicates how many fields were matched for this request. Using the parameters offset and limit is possible to paginate the results properly.
Notes:
status is still 200, with no data (empty array or empty downloaded file). limit of "0" (zero) will still return a valid response object with the proper count of matches. Additional methods should be added to query available options in lists, such as Countries, Constituency Sources, Services etc.