RIPE Database docs

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 ​

EnvironmentProtocolClient certEndpoint
TESTHTTPNohttp://rest-test.db.ripe.net
TESTHTTPSNohttps://rest-test.db.ripe.net
TESTHTTPSYeshttps://rest-cert-test.db.ripe.net
RIPEHTTPNohttp://rest.db.ripe.net
RIPEHTTPSNohttps://rest.db.ripe.net
RIPEHTTPSYeshttps://rest-cert.db.ripe.net

POST ​

Create an object in the RIPE database.

HTTPS is mandatory.

METHOD: POST ​

URI Format: /{source}/ ​

Path Parameters ​

namedescription
sourceRIPE or TEST (depending on location)
objectTypeobject type.

Query Parameters ​

namedescription
passwordPassword for maintainer authentication (one or more values).
unformattedKeep the formatting of the resource as provided in the request (spaces, end-of-lines) .
dry-runOptional. Perform validation but don't perform the update.

Headers ​

namedescription
AuthorizationBasic HTTP Authentication. The Authorisation request header can be used for either password or API key authentication.
To use password authentication, the value contains 'Basic' followed by the base64 encoding of the maintainer name and password separated by a colon. Please note that MD5 hashed passwords are deprecated and will be removed by end 2025.
To use API key authentication, the value contains a Base64-encoded value displayed when the API key was created.

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:

codedescription
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 ​

PUT ​

Updates an existing object in the RIPE Database.

HTTPS is mandatory.

Method: PUT ​

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

Path Parameters ​

namedescription
sourceRIPE or TEST (depending on location)
objectTypeThe object type
keyRequested object key

Query Parameters ​

namedescription
passwordPassword for maintainer authentication (one or more values).
unformattedKeep the formatting of the resource as provided in the request (spaces, end-of-lines).
dry-runOptional. Perform validation but don't perform the update.

Headers ​

namedescription
AuthorizationBasic HTTP Authentication. The Authorisation request header can be used for either password or API key authentication.
To use password authentication, the value contains 'Basic' followed by the base64 encoding of the maintainer name and password separated by a colon. Please note that MD5 hashed passwords are deprecated and will be removed by end 2025.
To use API key authentication, the value contains a Base64-encoded value displayed when the API key was created.

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 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 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:

codedescription
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 ​

DELETE ​

Deletes an object from the Database.

HTTPS is mandatory.

Method: DELETE ​

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

Path Parameters ​

namedescription
sourceRIPE or TEST (depending on location)
objectTypeobject type.
keyRequested RPSL Object primary key.

Query Parameters ​

namedescription
passwordPassword for maintainer authentication (one or more values). Mandatory.
reasonReason for deleting given object. Optional.
dry-runOptional. Perform validation but don't delete the object.

Headers ​

namedescription
AuthorizationBasic HTTP Authentication. The Authorisation request header can be used for either password or API key authentication.
To use password authentication, the value contains 'Basic' followed by the base64 encoding of the maintainer name and password separated by a colon. Please note that MD5 hashed passwords are deprecated and will be removed by end 2025.
To use API key authentication, the value contains a Base64-encoded value displayed when the API key was created.

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 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 (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:

codedescription
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 ​

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
  • 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 is supported by the Whois 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.

Example ​

For an example of how to use client certificate authentication, please see the appendix "Client Certificate Authentication".

API Key Authentication ​

API keys are a way to script (automate) authenticated queries and updates using the Whois REST API. They are generated using the web interface and are associated with a user's RIPE NCC Access account. They have a maximum validity of one year.

You can create as many different keys as you’d like. We suggest that you create a separate key for each application that you’d like to provide with access. That way, if you believe the key has been compromised, you can revoke access to that application without affecting other applications that you have provided with access.

API keys created for the RIPE database cannot be used with any other RIPE NCC service.

Example ​

For an example of how to use API keys, please see the appendix "API Keys".