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.
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 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:
The available methods and parameters are described in this document.
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.
.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:
|application/json||.json (default)||JSON. Should be pretty-printed by default. This will be the format used if no extension or
|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 be pretty-printed by default. 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.|
The API uses UTF8 as the request/response encoding. The result will also be compressed with Gzip if the request header
Accept-Encoding: compress, gzip is present.
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:
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.
|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
|callback||string||Only for JSONP resultsets, adds the
|scope||string||Collection of fieldnames to retrieve. Affects the resultset and the possible options for the parameter
The response structure is uniform, it first shows the status and length of the data, and then the data itself.
The response status can be ommitted from the response body, and be properly set at the response headers with 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.
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).
[Response body].version or
X-Version header points out the actual API version used.
[Response body].total or
X-Total header indicates how many fields were matched for this request. Using the parameters
limit is possible to paginate the results properly.
statusis still 200, with no data (empty array or empty downloaded file).
limitof "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.