# RIPE Database RESTful API

For more information about the REST paradigm, see https://en.wikipedia.org/wiki/Representational_state_transfer. All the services are accessible via HTTPS. Use of the Whois REST API is governed by the RIPE Database terms and conditions

# RESTful URI format

Each object in the RIPE Database has a unique locator URI, in the following format:

https://rest.db.ripe.net/{source}/{objecttype}/{key}

Where:

Source is the database source (e.g. RIPE).
Objecttype is the object type (e.g. inetnum)
key is the primary key(s)
- Normally key is a single attribute value.
- Use the nic-hdl attribute value for person or role object types.
- Combine the route(6) attribute value and origin attribute value for route or route6 object types (e.g. route 193.0.22.0/23AS3333).

# Environments

Environment	Protocol	Client cert	Endpoint
TEST	HTTP	No	http://rest-test.db.ripe.net
TEST	HTTPS	No	https://rest-test.db.ripe.net
TEST	HTTPS	Yes	https://rest-cert-test.db.ripe.net
RIPE	HTTP	No	http://rest.db.ripe.net
RIPE	HTTPS	No	https://rest.db.ripe.net
RIPE	HTTPS	Yes	https://rest-cert.db.ripe.net

# POST

Create an object in the RIPE database.

HTTPS is mandatory.

# METHOD: POST

# URI Format: /{source}/{objectType}

# Path Parameters

name	description
source	RIPE or TEST (depending on location)
objectType	object type.

# Query Parameters

name	description
password	Password for maintainer authentication (one or more values).
unformatted	Keep the formatting of the resource as provided in the request (spaces, end-of-lines) .
dry-run	Optional. Perform validation but don't perform the update.

# Headers

name	description
Authorization	Basic HTTP Authentication (opens new window). The Authorisation request header value contains 'Basic' followed by the base64 encoding of the maintainer name and password separated by a colon.

# HTTP Request Body

A WhoisResource containing the object to be created.

The client should specify the desired response format using the Accept: header in the HTTP request. If unspecified, the response defaults to XML.

The HTTP request must include a Content-Type: header for POST, PUT and DELETE. The HTTP response will include a Content-Type: header, and the response body will be encoded in the requested format.

The possible values that you can specify for the Accept/Content-Type header are:

application/xml for XML
application/json for JSON

Clients can also append an extension of .xml or .json to the request URL instead of setting an Accept: header. The server will return a response in the appropriate format for that given extension.

# HTTP Response Body

A WhoisResource containing the newly created, unfiltered object.

# HTTP Status Codes

Client applications should use the HTTP status code to detect the result of an operation. Any error messages will be included in the response body (see below).

Possible reasons for various HTTP status codes are as follows:

code	description
OK (200)	Successful update
Bad request (400)	Incorrect value for object type or key. The server is unable to understand and process the request.
Authentication failure (401)	Incorrect password
Forbidden (403)	Query limit exceeded.
Too Many Request (429)	Query limit exceeded.
Not Found (404)	No results were found (on a search request), or object specified in URI does not exist.
Method not Allowed (405)	No results were found (on a search request), or object specified in URI does not exist.
Conflict (409)	Integrity constraint was violated (e.g. when creating, object already exists).
Unsupported Media Type (415)	Unsupported/missing value for Accept/Content-Type header.
Internal Server Error (500)	The server encountered an unexpected condition which prevented it from fulfilling the request.

# Examples

Example XML Request:

curl -X POST -H 'Content-Type: application/xml' --data @form.txt 'https://rest.db.ripe.net/ripe/person?password=...'
Example JSON Request:

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' --data @form.txt 'https://rest.db.ripe.net/ripe/person?password=...'
Example Request using Basic authorisation (Basic AA1-TEST:AA1-TEST):

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Basic QUExLVRFU1Q6QUExLVRFU1QtUEFTU1dPUkQ=' --data @form.txt 'http://rest-test.db.ripe.net/test/person'
Example dry-run requests:

curl -X POST --data @form.txt 'https://rest.db.ripe.net/ripe/person?dry-run&password=...'

curl -X POST --data @form.txt 'https://rest.db.ripe.net/ripe/person?dry-run=true&password=...'

# PUT

Updates an existing object in the RIPE Database.

HTTPS is mandatory.

# Method: PUT

# URI Format: /{source}/{objectType}/{key}

# Path Parameters

name	description
source	RIPE or TEST (depending on location)
objectType	The object type
key	Requested object key

# Query Parameters

name	description
password	Password for maintainer authentication (one or more values).
unformatted	Keep the formatting of the resource as provided in the request (spaces, end-of-lines).
dry-run	Optional. Perform validation but don't perform the update.

# Headers

name	description
Authorization	Basic HTTP Authentication (opens new window). The Authorisation request header value contains 'Basic' followed by the base64 encoding of the maintainer name and password separated by a colon.

# HTTP Request Body

A WhoisResource containing the new version of the specified objects.

The client should specify the desired response format using the Accept: header in the HTTP request. If unspecified, the response defaults to XML.

The possible values that you can specify for the Accept/Content-Type header are:

application/xml for XML
application/json for JSON

# HTTP Response Body

A WhoisResource containing either the newly created, unfiltered object or the error message in case of a bad/unauthorized request.

# HTTP Status Codes

Client applications should use the HTTP status code to detect the result of an operation. Any error messages will be included in the response body (see below).

Possible reasons for various HTTP status codes are as follows:

code	description
OK (200)	Successful update
Bad request (400)	Incorrect value for object type or key. The server is unable to understand and process the request.
Authentication failure (401)	Incorrect password
Forbidden (403)	Query limit exceeded.
Too Many Request (429)	Query limit exceeded.
Not Found (404)	No results were found (on a search request), or object specified in URI does not exist.
Method not Allowed (405)	No results were found (on a search request), or object specified in URI does not exist.
Conflict (409)	Integrity constraint was violated (e.g. when creating, object already exists).
Unsupported Media Type (415)	Unsupported/missing value for Accept/Content-Type header.
Internal Server Error (500)	The server encountered an unexpected condition which prevented it from fulfilling the request.

# Error Response

If the request fails, any error messages will be returned in the response body, using the request Accept format (XML or JSON). This element will not be included on a successful response. Examples in WhoisResource.

# Examples

Example XML Request:

curl -X PUT -H 'Content-Type: application/xml' --data @form.txt 'https://rest.db.ripe.net/ripe/person/PP1-RIPE?password=...'
Example JSON Request:

curl -X PUT -H 'Content-Type: application/json' -H 'Accept:application/json' --data @form.txt 'https://rest.db.ripe.net/ripe/person/PP1-RIPE?password=...'
Example of a bad XML request when updating a mntner object using as request the person object from the first example:

curl -X PUT -H 'Content-Type: application/xml' --data @form.txt 'https://rest.db.ripe.net/ripe/mntner/PP1-RIPE?password=...'
Example of a bad JSON request when updating a mntner object using as request the person object from the first example:

curl -X PUT -H 'Content-Type: application/json' -H 'Accept:application/json' --data @form.txt 'https://rest.db.ripe.net/ripe/person/PP1-RIPE?password=...'
Example unfiltered using Basic authorisation header request (Basic AA1-TEST:AA1-TEST):

curl -X PUT -H 'Content-Type: application/json' -H 'Accept:application/json' -H 'Authorization: Basic QUExLVRFU1Q6QUExLVRFU1QtUEFTU1dPUkQ=' --data @form.txt 'http://rest-test.db.ripe.net/test/person/AA1-TEST'
Example dry-run requests:

curl -X PUT --data @form.txt 'https://rest.db.ripe.net/ripe/person/TP1-RIPE?dry-run&password=...'

curl -X PUT --data @form.txt 'https://rest.db.ripe.net/ripe/person/TP1-RIPE?dry-run=true&password=...'

# DELETE

Deletes an object from the Database.

HTTPS is mandatory.

# Method: DELETE

# URI Format: /{source}/{objectType}/{key}

# Path Parameters

name	description
source	RIPE or TEST (depending on location)
objectType	object type.
key	Requested RPSL Object primary key.

# Query Parameters

name	description
password	Password for maintainer authentication (one or more values). Mandatory.
reason	Reason for deleting given object. Optional.
dry-run	Optional. Perform validation but don't delete the object.

# Headers

name	description
Authorization	Basic HTTP Authentication (opens new window). The Authorisation request header value contains 'Basic' followed by the base64 encoding of the maintainer name and password separated by a colon.

# HTTP Request Body

The client should specify the desired response format using the Accept: header in the HTTP request. If unspecified, the response defaults to XML.

The possible values that you can specify for the Accept/Content-Type header are:

application/xml for XML
application/json for JSON

# HTTP Response Body

A WhoisResource containing the (filtered) deleted object.

# HTTP Status Codes

Client applications should use the HTTP status code to detect the result of an operation. Any error messages will be included in the response body (see below).

Possible reasons for various HTTP status codes are as follows:

code	description
OK (200)	Successful update
Bad request (400)	Incorrect value for object type or key. The server is unable to understand and process the request.
Authentication failure (401)	Incorrect password
Forbidden (403)	Query limit exceeded.
Too Many Request (429)	Query limit exceeded.
Not Found (404)	No results were found (on a search request), or object specified in URI does not exist.
Method not Allowed (405)	No results were found (on a search request), or object specified in URI does not exist.
Conflict (409)	Integrity constraint was violated (e.g. when creating, object already exists).
Unsupported Media Type (415)	Unsupported/missing value for Accept/Content-Type header.
Internal Server Error (500)	The server encountered an unexpected condition which prevented it from fulfilling the request.

# Examples

Example Request:

curl -X DELETE 'https://rest.db.ripe.net/ripe/person/pp1-ripe?password=123'
Example Request using Basic authorisation (Basic AA1-TEST:AA1-TEST):

curl -X DELETE -H 'Authorization: Basic QUExLVRFU1Q6QUExLVRFU1QtUEFTU1dPUkQ=' 'http://rest-test.db.ripe.net/test/person/AA1-TEST'
Example dry-run requests:

curl -X PUT --data @form.txt 'https://rest.db.ripe.net/ripe/person/TP1-RIPE?dry-run&password=...'

curl -X PUT --data @form.txt 'https://rest.db.ripe.net/ripe/person/TP1-RIPE?dry-run=true&password=...'

# Request / Response Encoding

Please take into account the following points to avoid unexpected encoding behaviour:

Objects are stored using the latin-1 (ISO-8859-1) character set.
If the request character set is not latin-1, then the request body is converted to latin-1. A question mark character ('?' or 0x3F) is used as a substitution character, if the character is outside the latin-1 character set.
The response should contain a warning, if conversion was necessary. known issue #291 (opens new window)
Unrecognised encodings that cannot be converted to latin-1 will result in an unsuccessful operation.
To be absolutely certain of what was stored in the database, do a follow-up query.
The REST API response will be in UTF-8.
We recommend to use UTF-8 character encoding in all REST API requests, but restrict the content to valid latin-1 characters.

# Update latency

It could take up to 10 seconds before an update becomes visible for lookup or search operations. For non-hierarchical object types (person, role, organisation,...), the typical latency is less than 1 second. For hierarchical objects types (inet(6)num, route(6), domain), it is about 3-5 seconds on average, up to 10 seconds maximum.

A way to work around this limitation is to rely on the response of the muting operation in REST API (PUT, POST, DELETE). These all return the object as it appears in the database in their response body after the successful update. This object is never filtered or altered in any way.

Any required passwords must also be supplied as part of the Uniform Resource identifier (URI) using the URI query parameter "password=". One parameter should be used for each password supplied. The pseudo attribute "password:" cannot be used in the HTTP request body. See "Email Updates" for more information.

# Client Certificate Authentication

Client Certificate Authentication (opens new window) is supported by our REST API. To use the client certificate service, you must have your own certificate: either from a certificate authority (CA) such as Let's Encrypt, or you can generate one yourself.

The key-cert object's client certificate status is validated by checking its notBefore and notAfter dates to ensure it is within its designated validity period. This involves comparing the current date against these dates: if the certificate is not yet valid (notBefore) or has expired (notAfter), it is considered invalid and an error is raised. This validation ensures that the certificate is only used within its valid time frame, maintaining secure and reliable authentication.

Additionally, signed updates are only considered valid for an hour after they are signed. After that the authentication will fail.

# Examples

Create your own certificate:
- Generate the private key: openssl genrsa -out client.key 2048
- Generate the Certificate Signing Request (CSR): openssl req -new -key client.key -out client.csr
- Generate the self-signed certificate using the CSR: openssl x509 -req -days 365 -in client.csr -signkey client.key -out client.crt
Example using curl and previous certificate:
- curl --cert client.crt --key client.key -X PUT --data @form.txt'https://rest-cert.db.ripe.net/ripe/person/TP1-RIPE?dry-run&password=...'