WHOIS REST API Search

Ed Shryane edited this page Oct 23, 2017 · 31 revisions

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

Documentation on the standard RIPE Database query flags.

Locations

  • http://rest.db.ripe.net/search
  • https://rest.db.ripe.net/search
  • http://rest-test.db.ripe.net/search
  • https://rest-test.db.ripe.net/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.

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

Example XML response:

<?xml version='1.0' encoding='UTF-8'?>
<whois-resources xmlns:xlink="http://www.w3.org/1999/xlink">
    <service name="search"/>
    <parameters>
        <inverse-lookup/>
        <type-filters/>
        <flags/>
        <query-strings>
            <query-string value="AS102"/>
        </query-strings>
        <sources>
            <source id="TEST"/>
        </sources>
    </parameters>
    <objects>
        <object type="aut-num">
            <link xlink:type="locator" xlink:href="http://rest-test.db.ripe.net/test/aut-num/AS102"/>
            <source id="test"/>
            <primary-key>
                <attribute name="aut-num" value="AS102"/>
            </primary-key>
            <attributes>
                <attribute name="aut-num" value="AS102"/>
                <attribute name="as-name" value="End-User-2"/>
                <attribute name="descr" value="description"/>
                <attribute name="admin-c" value="TP1-TEST" referenced-type="person">
                    <link xlink:type="locator" xlink:href="http://rest-test.db.ripe.net/test/person/TP1-TEST"/>
                </attribute>
                <attribute name="tech-c" value="TP1-TEST" referenced-type="person">
                    <link xlink:type="locator" xlink:href="http://rest-test.db.ripe.net/test/person/TP1-TEST"/>
                </attribute>
                <attribute name="mnt-by" value="OWNER-MNT" referenced-type="mntner">
                    <link xlink:type="locator" xlink:href="http://rest-test.db.ripe.net/test/mntner/OWNER-MNT"/>
                </attribute>
                <attribute name="source" value="TEST"/>
            </attributes>
            <tags/>
        </object>
        <object type="person">
            <link xlink:type="locator" xlink:href="http://rest-test.db.ripe.net/test/person/TP1-TEST"/>
            <source id="test"/>
            <primary-key>
                <attribute name="nic-hdl" value="TP1-TEST"/>
            </primary-key>
            <attributes>
                <attribute name="person" value="Test Person"/>
                <attribute name="address" value="Singel 258"/>
                <attribute name="phone" value="+31 6 12345678"/>
                <attribute name="nic-hdl" value="TP1-TEST"/>
                <attribute name="mnt-by" value="OWNER-MNT" referenced-type="mntner">
                    <link xlink:type="locator" xlink:href="http://rest-test.db.ripe.net/test/mntner/OWNER-MNT"/>
                </attribute>
                <attribute name="source" value="TEST" comment="Filtered"/>
            </attributes>
            <tags/>
        </object>
    </objects>
    <terms-and-conditions xlink:type="locator" xlink:href="http://www.ripe.net/db/support/db-terms-conditions.pdf"/>
</whois-resources>

Example JSON response:

{"service": {
    "name": "search"
},
"parameters": {
    "inverse-lookup": {
        "inverse-attribute": []
    },
    "type-filters": {
        "type-filter": []
    },
    "flags": {
        "flag": []
    },
    "query-strings": {
        "query-string": [
            {
                "value": "AS102"
            }
        ]
    },
    "sources": {
        "source": [
            {
                "id": "TEST"
            }
        ]
    }
}, "objects": {
    "object": [
        {
            "type": "aut-num",
            "link": {
                "xlink:type": "locator",
                "xlink:href": "http://rest-test.db.ripe.net/test/aut-num/AS102"
            },
            "source": {
                "id": "test"
            },
            "primary-key": {
                "attribute": [
                    {
                        "name": "aut-num",
                        "value": "AS102"
                    }
                ]
            },
            "attributes": {
                "attribute": [
                    {
                        "name": "aut-num",
                        "value": "AS102"
                    },
                    {
                        "name": "as-name",
                        "value": "End-User-2"
                    },
                    {
                        "name": "descr",
                        "value": "description"
                    },
                    {
                        "link": {
                            "xlink:type": "locator",
                            "xlink:href": "http://rest-test.db.ripe.net/test/person/TP1-TEST"
                        },
                        "name": "admin-c",
                        "value": "TP1-TEST",
                        "referenced-type": "person"
                    },
                    {
                        "link": {
                            "xlink:type": "locator",
                            "xlink:href": "http://rest-test.db.ripe.net/test/person/TP1-TEST"
                        },
                        "name": "tech-c",
                        "value": "TP1-TEST",
                        "referenced-type": "person"
                    },
                    {
                        "link": {
                            "xlink:type": "locator",
                            "xlink:href": "http://rest-test.db.ripe.net/test/mntner/OWNER-MNT"
                        },
                        "name": "mnt-by",
                        "value": "OWNER-MNT",
                        "referenced-type": "mntner"
                    },
                    {
                        "name": "source",
                        "value": "TEST"
                    }
                ]
            },
            "tags": {
                "tag": []
            }
        },
        {
            "type": "person",
            "link": {
                "xlink:type": "locator",
                "xlink:href": "http://rest-test.db.ripe.net/test/person/TP1-TEST"
            },
            "source": {
                "id": "test"
            },
            "primary-key": {
                "attribute": [
                    {
                        "name": "nic-hdl",
                        "value": "TP1-TEST"
                    }
                ]
            },
            "attributes": {
                "attribute": [
                    {
                        "name": "person",
                        "value": "Test Person"
                    },
                    {
                        "name": "address",
                        "value": "Singel 258"
                    },
                    {
                        "name": "phone",
                        "value": "+31 6 12345678"
                    },
                    {
                        "name": "nic-hdl",
                        "value": "TP1-TEST"
                    },
                    {
                        "link": {
                            "xlink:type": "locator",
                            "xlink:href": "http://rest-test.db.ripe.net/test/mntner/OWNER-MNT"
                        },
                        "name": "mnt-by",
                        "value": "OWNER-MNT",
                        "referenced-type": "mntner"
                    },
                    {
                        "name": "source",
                        "value": "TEST",
                        "comment": "Filtered"
                    }
                ]
            },
            "tags": {
                "tag": []
            }
        }
    ]
}, 
"terms-and-conditions": {
    "xlink:type": "locator",
    "xlink:href": "http://www.ripe.net/db/support/db-terms-conditions.pdf"
}
}
  • A search request with invalid flag
http://rest.db.ripe.net/search?source=ripe&query-string=PP1-RIPE&flags=k

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/search?query-string=PP1-RIPE&amp;source=RIPE&amp;flags=k"/>
    <errormessages>
        <errormessage severity="Error" text="Invalid source '%s'">
            <args value="RIPE"/>
        </errormessage>
    </errormessages>
    <terms-and-conditions xlink:type="locator" xlink:href="http://www.ripe.net/db/support/db-terms-conditions.pdf"/>
</whois-resources>

Example JSON response:

{
  "link" : {
    "type" : "locator",
    "href" : "http://rest.db.ripe.net/search?query-string=PP1-RIPE&source=RIPE&flags=k"
  },
  "errormessages" : {
    "errormessage" : [ {
      "severity" : "Error",
      "text" : "Invalid source '%s'",
      "args" : [ {
        "value" : "RIPE"
      } ]
    } ]
  },
  "terms-and-conditions" : {
    "type" : "locator",
    "href" : "http://www.ripe.net/db/support/db-terms-conditions.pdf"
  }
}
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.