# RESTful API Queries

Queries are supported by the RESTful API using the GET method. There are two ways of using the API. One way looks up a specific object and only returns a single object. The other searches for objects matching specified criteria. The search may return large numbers of objects.

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

  • application/xml for XML
  • application/json for JSON
  • text/plain for TEXT

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

# REST API Lookup

This can be done from the command line using a third party software package, from a script or in a browser. It will only return the one specific object requested. For lookups on address space, it will not return the encompassing object if the specified object does not exist. By default objects are filtered as described in Filtering the Query Response.

Returns an object from the RIPE Database.

curl 'https://rest.db.ripe.net/ripe/inetnum/193.0.0.0%20-%20193.0.7.255?unfiltered'

Any spaces in the command must be encoded. The response will be returned by default in XML format. Alternatively JSON or text/plain can be returned:

curl -H 'Accept: application/json'

Additional resources:


# Method: GET

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

# Path Parameters

name description
source Source name (RIPE, TEST or a GRS source name).
objectType Type of given object.
key Primary key of the given object.

# Query Parameters

name description
password Password for maintainer authentication (one or more values).
unfiltered The returned object should not be filtered ("notify" and "e-mail" attributes will not be removed).
unformatted Return the resource in its original formatting (including spaces, end-of-lines).

# 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 Response Body

A WhoisResource containing the object.

By default the response object is filtered as described in Filtering the Query Response. To return the unfiltered object specify the unfiltered query parameter. To obtain an unfiltered maintainer object (including all "auth:" attributes), the request must be authenticated.

# 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 'http://rest.db.ripe.net/ripe/mntner/RIPE-DBM-MNT'

  • Example JSON request:

    curl -H 'Accept: application/json' 'http://rest.db.ripe.net/ripe/mntner/RIPE-DBM-MNT'

  • Example text/plain request:

    curl -H 'Accept: text/plain' 'http://rest.db.ripe.net/ripe/mntner/RIPE-DBM-MNT'

  • Example unfiltered request:

    curl 'http://rest-test.db.ripe.net/test/person/AA1-TEST?unfiltered'

  • Example unfiltered using password parameter request:

    curl 'http://rest-test.db.ripe.net/test/person/AA1-TEST?password=AA1-TEST-PASSWORD&unfiltered'

  • Example unfiltered using Basic authorisation header request (Basic AA1-TEST:AA1-TEST):

    curl -H 'Authorization: Basic QUExLVRFU1Q6QUExLVRFU1QtUEFTU1dPUkQ=' 'http://rest-test.db.ripe.net/test/person/AA1-TEST?unfiltered'

  • Example bad request when source is incorrect:

    curl 'http://rest.db.ripe.net/pez/person/PP1-RIPE'

  • Example request with encoded query parameter:

    curl 'http://rest.db.ripe.net/ripe/inetnum/193.0.0.0%20-%20193.0.7.255.json'

This can be run in the same ways as the REST API Lookup. This search provides the same set of results as a web or command line query will provide.

Offers the well-known whois search via a rest-like interface.

Documentation on the standard RIPE Database query flags.

As with the lookup, any spaces in the query string must be encoded. The response will be returned in XML format by default. Alternatively, JSON or text/plain can be returned.

By default the response objects are filtered as described in Filtering the Query Response. To return unfiltered objects specify the flags query parameter with the B or no-filtering flag value. To obtain an unfiltered maintainer object (including all "auth:" attributes), use the REST API lookup.

# Locations

Environment endpoint/search

# HTTP Method: GET

# URI Format: /search?source={source}&query-string={query-string}...

# URI Path Parameters

None.

# URI Query Parameters

name description
source Optional, default is RIPE for http://rest.db.ripe.net. Can specify RIPE or GRS source names. It's possible to specify multiple sources (one source per parameter). Use http://rest-test.db.ripe.net to search the TEST datasource.
query-string The search term. Mandatory.
inverse-attribute Optional. If specified the query is an inverse lookup on the given attribute, if not specified the query is a direct lookup search.
include-tag Optional. Only show RPSL objects with given tags. Can be multiple.
exclude-tag Optional. Only show RPSL objects that do not have given tags. Can be multiple.
type-filter Optional. If specified the results will be filtered by object-type, multiple type-filters can be specified.
flags Optional query-flags. Use separate flags parameters for each option (see examples)
unformatted Don't reformat RPSL objects, preserve all spaces, tabs and newlines in attribute values.
managed-attributes Flag which RPSL attributes are managed by the RIPE NCC.
resource-holder Include the resource holder Organisation (id and name).
abuse-contact Include the Abuse contact email address of the resource, if applicable.
limit Maximum number of RPSL objects to return in the response.
offset Return RPSL objects from a specified offset. This allows for paging.
roa-check Validate route(6) objects against RPKI ROAs and report on any conflicts.

# HTTP Response Body

A WhoisResource containing the query result.

# HTTP Status Codes

code description
200 Search successful
400 Illegal input - incorrect value in one or more of the parameters
404 No object(s) found

Note that search response can be enormous. Hence, it is streamed on the server side, which means that if there is any error during processing your search, the HTTP response will still be 200. In this case, there will be the corresponding error messages inside the errormessages element in the response body (see Whois Resources).

# Examples

  • Valid inverse lookup query on an org value, filtering by inetnum:

    http://rest.db.ripe.net/search?inverse-attribute=org&type-filter=inetnum&source=ripe&query-string=ORG-RIEN1-RIPE

  • Search for objects of type organisation on the same query-string and specifying a preference for non recursion:

    http://rest.db.ripe.net/search?inverse-attribute=org&flags=no-referenced&type-filter=inetnum&source=ripe&query-string=ORG-RIEN1-RIPE

  • A search on multiple sources:

    http://rest.db.ripe.net/search?source=ripe&source=apnic-grs&flags=no-referenced&flags=no-irt&query-string=MAINT-APNIC-AP

  • A search on multiple sources and multiple type-filters:

    http://rest.db.ripe.net/search?source=ripe&source=apnic-grs&query-string=google&type-filter=person&type-filter=organisation

  • A search using multiple flags:

    http://rest.db.ripe.net/search?source=ripe&query-string=aardvark-mnt&flags=no-filtering&flags=no-referenced

  • A search request with invalid flag

    http://rest.db.ripe.net/search?source=ripe&query-string=PP1-RIPE&flags=k

# REST API Metadata

# Metadata (list sources)

List available sources.

# Locations

Environment endpoint/metadata/sources

# HTTP Method: GET

# URI Format: /metadata/sources

# URI Path Parameters

None.

# HTTP Response Body

A WhoisResource containing all available sources.

# HTTP Status Codes

code description
200 Request successful

# Examples

http://rest.db.ripe.net/metadata/sources.json

Example XML response:

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <whois-resources xmlns:xlink="http://www.w3.org/1999/xlink">
  <link xlink:type="locator" xlink:href="http://rest.db.ripe.net/metadata/sources"/>
  <service name="getSupportedDataSources"/>
  <sources>
      <source name="RIPE" id="ripe"/>
      <source name="TEST" id="test"/>
  </sources>
  <grs-sources>
      <source name="TEST-GRS" id="test-grs" grs-id="test-grs"/>
  </grs-sources>
  </whois-resources>

Example JSON response:

{
  "link": {
    "xlink:type": "locator",
    "xlink:href": "http://rest.db.ripe.net/metadata/sources"
  }, 
  "service" : {
    "name" : "getSupportedDataSources"
  },
  "sources": {
    "source": [
      {
        "name": "RIPE",
        "id": "ripe"
      },
      {
        "name": "TEST",
        "id": "test"
      }
    ]
  },
  "grs-sources": {
    "source": [
      {
        "name": "TEST-GRS",
        "id": "test-grs",
        "grs-id": "test-grs"
      }
    ]
  }
}

# Metadata (Object Template)

Returns the RPSL template for given object type.

# Resources

Environment endpoint/metadata/templates

# HTTP Method: GET

# URI Format: /metadata/templates/{objectType}

# URI Path Parameters

name description
objectType The object type for which the template is requested

# HTTP Response Body

A WhoisResource containing the template of the specified type.

# HTTP Status Codes

code description
200 Request successful
400 Illegal input - incorrect objectType

# Examples

Example querying for the template of PERSON:

curl http://rest.db.ripe.net/metadata/templates/person.xml

# REST API Geolocation

Lookup geolocation and language attributes for a particular IPv4 or IPv6 address.

Returns geolocation information for the specified address.

For further background information on the Geolocation feature, refer to the RIPE Labs article here: https://labs.ripe.net/Members/denis/geolocation-prototype-for-ripe-database

# Locations

Environment endpoint/geolocation

# HTTP Method: GET

# URI Format: /geolocation?ipkey={key}

# URI Path Parameters

None.

# URI Query Parameters

name description
key IPv4 or IPv6 address

# HTTP Response Body

A WhoisResource containing locator URIs to matching objects.

For non-200 OK responses, the response body will be in plaintext.

# HTTP Status Codes

code description
200 Geolocation and/or language data was found for the specified address
404 No geolocation data found, or the address does not exist

# Examples

curl https://rest.db.ripe.net/geolocation?ipkey=10.0.0.0

# REST API Abuse Contact

Lookup abuse contact email for an internet resource (IPv4 address, range or prefix, IPv6 address or prefix, AS number).

# Locations

Environment endpoint/abuse-contact

# HTTP Method: GET

# URI Format: /abuse-contact/{resource}

# URI Path Parameters

name description
resource IPv4 address, range or prefix, IPv6 address or prefix, AS number

# URI Query Parameters

None.

# HTTP Response Body

An AbuseResources containing locator URIs to matching objects.

# HTTP Status Codes

code description
200 Matching resource found and abuse contact returned correctly
404 Resource specified was not found

# Examples

curl http://rest-test.db.ripe.net/abuse-contact/AS3333

# REST API Version

Show a specific version of a RIPE Database object.

# Resources

Environment endpoint

# Method: GET

# URI Format: /{source}/{objecttype}/{key}/versions/{versionnumber}

# URI Parameters

name description
source RIPE or TEST
objecttype Object type
key RPSL object key
versionnumber Object version

# Response Body

A WhoisResource containing the requested version of the object or the error message in case of Bad request (see GET).

# Status Codes

code description
200 Version was found
400 Bad request - invalid source, key or version
404 Requested object version not found

# Examples

curl 'https://rest-test.db.ripe.net/TEST/aut-num/AS102/versions/2'

# REST API Versions

Lists all versions of RIPE Database object, including the date and operation for each version.

# Resources

Environment endpoint

# Method: GET

# URI Format: /{source}/{objecttype}/{key}/versions

# URI Parameters

name description
source RIPE or TEST
objecttype Object type
key Requested RPSL Object primary key

# Response Body

A WhoisResource containing information about updates for the requested object or the error message in case of Bad request (see GET).

# Status Codes

code description
200 Success (object found)
400 Illegal input - incorrect key syntax
404 Object not found

# Examples

Example Request:

curl 'https://rest-test.db.ripe.net/TEST/aut-num/AS102/versions'

# Authentication

RESTful API queries can be authenticated in order to retrieve the full object details, e.g. maintainers.

RESTful API queries can be authenticated using the following methods:

  • Password: You can choose between using password query parameter or basic authentication.
  • SSO cookie: If you are using the web application you can automatically be authenticated in one mntner if that mntner is associated to your SSO account.
  • Client certificate: You can supply your own certificate, and it is checked against the queried object's mntner key-certs