FIRST 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. Its first application is the Members around the world map.
It's also being worked to comply with Global IRT and propose a Global IRT API to be able to share abuse contact data.
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 (/data
in the case of FIRST API, /global-irt
for FIRST.Org Global IRT) and the version of the API under the endpoint. These are the available endpoints:
Repository (sourcename) | Endpoint URL | Status |
---|---|---|
FIRST API v1 | https://api.first.org/data/v1 | Stable |
FIRST.Org Global IRT | https://api.first.org/global-irt/v1 | Beta |
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 the request/response 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 bar
bar
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 a number between 1 and 100. |
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.