RIPE Database REST API Documentation

Benedetto Fiorelli — Feb 11, 2011 02:05 PM
Filed under:
The RIPE Database RESTful Web Services API are REST interfaces to the Whois Database. The latest version of the API offers full CRUD support and also new advanced methods to programmatically manipulate RIPE Database objects. Find here some documentation.

RIPE Database RESTful Web Services, the API

Update 28 August 2012: This Labs article will no longer be kept up to date. Please refer to the developer documentation page about this topic and others at:

http://www.ripe.net/data-tools/developer-documentation

The RIPE Database RESTful Web Services API are REST interfaces to the Whois Database.

In compliance with the REST paradigm our web services are invoked via plain HTTP requests, using the HTTP method that is most appropriate for the given kind of request. The web services responses are returned in the form of an HTTP response that contains a response code describing success or failure of the operation, some response headers and eventually a response body.

Warning

Important

All the services are also accessible on the HTTPS protocol.

The Update Services require password authentication. For this reason HTTPS is highly recommended on these services and in future releases their access on HTTP may be deprecated.

Also Query Services can be executed on HTTPS but we suggest to do so only if confidentiality, integrity and verification are strictly required.

As announced on 13th of October 2011, the service is now in supported BETA state and has been migrated to our production servers. It is now accessible from https://apps.db.ripe.net instead of https://lab.db.ripe.net, please update your endpoint address configuration accordingly.

All the services, on all the HTTP methods, are also accessible on the HTTPS protocol. HTTPS should be used for all those services that require password authentication, for example for the Update Services. But also simpler Query Services can be executed on HTTP if confidentiality, integrity and verification are required.

How to use this documentation

In order to simplify this document and make it easy to find or bookmark a specific section that may be of your interest we have decided to group the services by their purposes and by similarity in adopted conventions, schemas, response codes.

The main groups are the following:

The Query Services

The response styles

The two supported response formats are XML and JSON.

XML is the best choice for clients implemented in server side services, web applications and desktop tools that can take advantage of the powerful parsing or binding API that platforms like Java, C#, Python provide these days.

JSON on the other hand is the best choice for those lightweight client components that don't need to reconstruct a full-fledged object model and also don't want to depend on third party parsing or binding libraries that may complicate the portability across different browsers.

For example Javascript, Ajax and Flash developers may want to use the JSON response style and render their own responses using some JSON manipulation or templating solution.

Features exclusive to this demo

The current version of the services also exposes responses in HTML format with the only purpose of showcasing the power and flexibility of the REST / XML model. HTML responses are dynamically generated server side using few simple XSLT documents that define the XML to HTML transformation. The same technology may be used by any client to manipulate or transform XML responses.

Anyway XSLT is not the only choice to postprocess our responses in a declarative way (without having to implement parsing or binding).

There many other templating technologies that can be adopted to XML or JSON, like XQuery LINQ or even MVC templating engines like FreeMarker Velocity json-template , jemplate , etc.

Warning

Future support for HTML

It's important to note that the HTML feature is just a proof of concept and may be removed, changed or extended in further development phases. Any client dependency on this response style will not be supported.

Content negotiation

So how can you negotiate the response style?

All our services support the standard HTTP/1.1 content negotiation method.

The client  "Accept" and "Content-Type" HTTP Headers.

The client must specify the desired response style setting the "Accept" header, otherwise the default response style will be XML. The HTTP response body will be therefore formatted in the requested style and a "Content-Type" header in the HTTP response will confirm the setting.

The two possible values that you can specify for the Accept header are:

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

This release also showcases a more human readable negotiation through request URI extension. Clients can append an extension of .xml, .json or .html to their request URL and the server will return a response in the appropriate response style for that given extension. The URI extension overrides any Accept header setting.

Warning

Important

Client applications or services built on top of our services "must" use the standard HTTP/1.1 header based negotiation, not the extension based method.

URI extension negotiation is only a demo feature and is not officially supported.

Other important thing to remember is that not all browsers support XML. If you specify a .xml extension or no extension at all the response style will be XML and your browser may not be able to render it, for example the actual versions of Google Chrome and Safary will show a white page and the XML content will be visible only if you inspect the page source code. On the other hand Firefox may be able to render the XML.

For this reason if you want to test the Query API using a browser better you install a dedicate extension or plugin (for example "REST Client", "Http Resource Test" or "Tamper Data" are all valid Firefox extensions).

The REST API specification for the Query Services

The current version of the RIPE Database REST Query API exposes the following interfaces.

[Service URL] = http://apps.db.ripe.net/whois

Service interface HTTP URL HTTP Method HTTP GET Parameters
getSupportedDataSources [Service URL]/sources GET
lookup [Service URL]/lookup/{source} /{primary-key} GET
grs-lookup [Service URL]/grs-lookup/{grs-source} /{primary-key} GET
search [Service URL]/search GET

query-string={query-string} ..*,

source= {source} ..*,

inverse-attribute=attribute-name ..*,

type-filter={object-type}..*, flags= {query-flags}

grs-search [Service URL]/grs-search GET query-string={query-string} ..*,

source= {grs-source} ..*,

inverse-attribute=attribute-name ..*,

type-filter={object-type}..*, flags= {query-flags}

getObjectTemplate [Service URL]/templates/{object-type} GET

getSupportedDataSources

The getSupportedDataSources interface returns the set of all the RIRs that the REST services query proxies. This is the list of Regional Internet Registry organisations that you can query through the lookup and  search methods.

Of the returned set currently only the ripe, afrinic and apnic can be used since they are compliant with the RIPE Database data model and character encoding.

The service URL is:

http://apps.db.ripe.net/whois/sources

lookup

The lookup interface returns the single object that satisfy the key conditions specified as path parameters via the source and the primary-key arguments, i.e.:

'http://apps.db.ripe.net/whois/lookup/ {source} {primary-key} '

Example query:

http://apps.db.ripe.net/whois/lookup/ripe/mntner/RIPE-DBM-MNT

grs-lookup

The grs-lookup interface returns the single object that satisfy the key conditions specified as path parameters via the grs-source and the primary-key arguments, i.e.:

'http://apps.db.ripe.net/whois/grs-lookup/ {grs-source} {primary-key} '

Example query:

http://apps.db.ripe.net/whois/grs-lookup/apnic-grs/mntner/MAINT-APNIC-AP

search

The search interface resembles a standard Whois client query with the extra features of multi-registry client, multiple response styles that can be selected via content negotiation and with an extensible URL parameters schema.

Two more additional features compared to standard clients are:

  • Query using multiple query-strings: It is possible to specify more than one query-string by just repeating the query-string parameter, i.e.:

...query-string=NINJA-MNT&query-string=RIPE-DBM-MNT&KEY=DW-MNT

All the other parameters will be applied to all the query-strings so the result will be a set of whois objects satisfying the request. Duplicate whois objects are automatically discarded by the system.

Actually there is a limit of 5 query-strings per request.

  • Query using multiple sources: It is possible to specify multiple sources for the same request. This will execute the request on all the specified sources. Queries are executed on the online Whois servers, not on mirrored data, so they return live objects directly from the trusted sources.

In case of system exception on any of the sources the client will get an appropriate error code in response.

The two features can be combined so that in one request multiple query-strings will be looked up in multiple RIRs.

Example:

...source=ripe&source=apnic

Further documentation on the standard Whois Database Query flags can be found on the RIPE Whois Database Query Reference Manual .

The service URL must be:

'http://apps.db.ripe.net/whois/search'

and the following parameters can be specified as HTTP GET parameters:

Parameter Value Mandatory Multiple Description
query-string {query-string} Y Y It is possible to specify multiple query-strings in a single request
source {source} Y Y

The source RIR that you want to query for the given query-string, it is possible to specify multiple sources.

inverse-attribute {attribute-name} N Y If specified the query is an inverse lookup on the given attribute, if not specified the query is a direct lookup search
type-filter {object-type} N Y If specified the results will be filtered by object-type, multiple type-filters can be specified
flags {query-flags} N N specifies an optional sequence ofquery-flags

 

For example the next query describes a valid inverse lookup query on an org value, filtering by inetnum:

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

On the other hand a direct search for objects of type organisation on the same query-string and specifying a preference for non recursion would be:

http://apps.db.ripe.net/whois/search?inverse-attribute=org&flags=r&type-filter=inetnum&source=ripe&query-string=ORG-NCC1-RIPE

A search on multiple sources:

http://apps.db.ripe.net/whois/search?source=ripe&source=apnic&flags=rC&query-string=MAINT-APNIC-AP

A search on multiple sources and multiple query-strings:

http://apps.db.ripe.net/whois/search?source=ripe&source=apnic&query-string=MAINT-APNIC-AP&query-string=pp-ripe&flags=BC

A search on multiple sources and multiple query-strings and multiple type-filters:

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

grs-search

The grs-search interface has exactly the same features of the search, with the only difference that in the source parameter you will be specifying one or more GRS sources.
The query will therefore be executed on the GRS sources that you specify and will return data from the respective mirrors maintained in the RIPE Database platform.

The service URL is:

'http://apps.db.ripe.net/whois/grs-search'

For example the following query search for the query string 193/8 on the ripe, apnic, arin, lacnic, radb GRS mirrors:

http://apps.db.ripe.net/whois/grs-search?flags=&source=apnic-grs&source=arin-grs&source=lacnic-grs&source=radb-grs&query-string=193%2F8

getObjectTemplate

The getObjectTemplate interface returns the rpsl template for a given object-type to be specified as path argument:

'http://apps.db.ripe.net/whois/templates/{object-type} '

Example:

http://apps.db.ripe.net/whois/templates/person

source

A source is an identifier for a Regional Internet Registry organisation. The valid values can be retrieved invoking the getSupportedDataSources method with text/xml content negotiation and issuing the following XPath expression against the XML response body:

whois-resources/sources/source/@id

The Update Services only support sources ripe and test.

grs-source

The identifier of a GRS sources. GRS identifiers always end with -grs. The GRS source that we support in this release are:
  • ripe-grs
  • apnic-grs
  • arin-grs
  • lacnic-grs
  • radb-grs
  • afrinic-grs

object-type

Any of the object types supported by the latest RPSL specification.

primary-key

The primary-key argument is required in the lookup method. It must be set to the value of the primary key attribute for the object you are trying to find.

For example, the primary key of a maintainer object is the value of the mntner attribute.

A query that specifies a primary key of RIPE-DBM-MNT for a mantainer object would look like:

http://apps.db.ripe.net/whois/lookup/ripe/mntner/RIPE-DBM-MNT

Object types route and route6 have a double valued primary key since they are not uniquely identifiable by their respective main attributes route and route6.

For this reason the primary key for objects of type route and route6 must be composed of the route/route6 attribute plus the value of the origin attribute. The REST service requires the values to be separated by a / character.

Example:

http://apps.db.ripe.net/whois/lookup/ripe/route/193.6.23.0/24/AS2547

query-string

A query-string is the string value that you would specify in a standard whois database query that may return multiple objects matching this string in one of their direct or inverse lookup attributes.

query-flags

By using the search method it is possible to specify query flags via the optional flags parameter.  Multiple flags can be specified by simply concatenating them as a single value.

Example:

http://apps.db.ripe.net/whois/search?source=ripe&query-string=ORG-NCC1-RIPE&flags=rC

Supported flags for this release are:

Flag Explanation
B Show entire object including all e-mail addresses.
C Turn off the 'most specific' behaviour.
d Enables the use of -m,-M,-x,-l,-L to return reverse delegation domain objects.
G Turn off logical grouping of objects and lists objects according to type.
K Only the primary keys of an object are returned. Does not apply to role and person.
L Return all less specific inetnum, inet6num, route or route6 objects, including exact match.
l First level less specific inetnum, inet6num, route or route6 objects, excluding exact match.
m First level more specific inetnum, inet6num, route or route6 objects, excluding exact match.
M All more specific inetnum, inet6num, route or route6 objects, excluding exact match.
r Switch off recursive search for contact information.
R Switch off referrals for domain lookups.
x Only an exact match on a prefix will be performed.

Further documentation on the Whois Database Query can be found on the RIPE Database Query Reference Manual .

Error codes

In compliance with the REST paradigm any error information is returned in the form of a standard HTTP response with an HTTP status code describing the error and a text/plain body message describing the exception causing the error response.

In this version we are using only standard HTTP codes (http://www.iana.org/assignments/http-status-codes ).

A future release may define specialized error codes extending but this is a decision we haven't finalized yet.

The following table gives a brief description of the mapping between standard Whois V.3 responses and the related REST services status codes. Consider this table as just an example of the error mapping strategy, it may change with future releases.

System Exception Whois Error HTTP Status Code
IllegalArgumentException Bad Request (400)
IllegalStateException Internal Server Error (500)
UnsupportedOperationException Bad Request (400)
ObjectNotFoundException Not Found (404)
IllegalStateException Internal Server Error (500)
IOException Internal Server Error (500)
SystemException Internal Server Error (500)
TooManyResultsException Internal Server Error (500)
WhoisServerException No Entries Found (101) Not Found (404)
WhoisServerException Unknown Source (102) Bad Request (400)
WhoisServerException Unknown Object Type (103) Bad Request (400)
WhoisServerException Unknown Attribute in Query (104) Bad Request (400)
WhoisServerException Attribute Is Not Inverse Searchable (105) Bad Request (400)
WhoisServerException No Search Key Specified (106) Bad Request (400)
WhoisServerException Input Line too Long (107) Bad Request (400)
WhoisServerException Bad Character in Input (108) Bad Request (400)
WhoisServerException Invalid Combination of Flags Passed (109) Bad Request (400)
WhoisServerException Access Denied (201) Forbidden (403)
WhoisServerException Access Control Limit Reached (202) Forbidden (403)
WhoisServerException Address Passing Not Allowed (203) Bad Request (400)
WhoisServerException Maximum Referral Lines Exceeded (204) Internal Server Error (500)
WhoisServerException Connection Refused (208) Forbidden (403)
WhoisServerException Connection Has Been Closed(301) Internal Server Error (500)
WhoisServerException Referral Timeout (302) Internal Server Error (500)
WhoisServerException No Referral Host (303) Internal Server Error (500)
WhoisServerException Referral Host Not Responding (304) Internal Server Error (500)

Clients should avoid any form of coupling with the the text/plain error message contained in response body since it may change between different releases of the API and is only intended as a starting point for debugging the real causes of the exception event.

The following table show an example of a possible mapping for client side error messages generic enough for the four HTTP error codes:

HTTP Status Code Error Message
Bad Request (400) The service is unable to understand and process the query.
Forbidden (403) Query limit exceeded.
Not Found (404) No results were found for Your search " Search term "
Internal Server Error (500) The server encountered an unexpected condition which prevented it from fulfilling the request.

The Update Services

The Update Services are REST interfaces that you can use to Create, Update and Delete RIPE Database objects. Additionally we consider part of the Update family also a set of Modify interfaces. Modify interfaces simplify all those object manipulations that would otherwise require complicate client side workflows, like modifying an attribute at a given index, replacing all the attributes of a given type with new attributes, adding attributes at a given index, etc. New modify interfaces will be provided in future depending on the feedback that we will receive on this project.

Unlike the legacy interfaces Mail Update and Syncupdates all the new Update REST Services accept only one single object per request, they do not accept multiple objects in the same request.

The precondition of one object per request has been imposed to avoid partial update situations in which multiple objects need to be processed in the same request and not all the updates have a successful outcome. An interface that allows for partial updates may be considered more generic but it has major weaknesses that in terms of design can be considered flaws:

  • it requires the definition of a complex message protocol to communicate what failed and what succeeded in the entire sequence of processing,
  • the clients need to handle this complex message protocol, parsing response messages rather than just checking a simple status code, that means less usable interface and error prone code replicated on all clients,
  • it is not coherent with the REST paradigm, a REST request succeeds or fails, a partial modification of a resource in the world of HTTP is considered a failure and the result is a broken resource,
  • it precludes the introduction of ACID transactionality. A transaction succeeds or fails, if it fails everything has to go back to the initial state, eventually triggering rollback processes if required, a partial change in terms of transaction is a corruption of integrity.

For all these reasons and considering that we are just creating building blocks that can still be combined to build more convolute interfaces, all our REST Update interfaces for now are considered atomic, they accept only one object per request and every request can succeed or fail but not be applied in part.

Clients will still be able to build well defined sequences of requests and handle single failures on the base of success or failure of the single request in the sequence.

The XML schemas

The Create and Update Services require clients to send an XML representation of the RIPE Database object that they want to create or update. The client must embed the XML in the body of the HTTP request.

The schema to be used is a simplified version of the schema that we designed for the Query Services, simplified because the Query Services decorate the response with many details that are not required in the context of an update request.

If you have used the lookup service you have seen how the XML response is structured. The same structure needs to be used in the context of a Create or Update request, but you don't need to specify all the link elements nor metadata attributes like service or referenced-type.

For example the following is a valid XML that you may submit in the HTTP request for the Create and the Update services:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources>
<objects>
<object type="person">
<source id="test"/>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="Singel 258"/>
<attribute name="phone" value="+31-1234567890"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="mnt-by" value="PP-MNT" />
<attribute name="nic-hdl" value="AUTO-1" />
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="source" value="TEST"/>
</attributes>
</object>
</objects>
</whois-resources>

It is very simple and the same structure is valid for any object type, all you need to specify are the elements whois-resources, objects, object, source, attributes, attribute as in the previous example.

The source id can be "ripe" or "test", other remote registries are not valid at this moment but it could be possible in future to extend the service to other registries that support same RIPE Database data model.

The Update Services also support other features like attribute comments and comma separated values.

Comments are the equivalent of end of line comments that you would use in RPSL, with the difference that these comments are normalized, every attribute can have it's own comment but there is no concept of continuation lines in all our REST Services, every attribute has one value and can have one comment. This is how you can define an attribute comment.

<attribute name="mnt-by" value="GG-MNT" comment="This is my maintainer" />

For some attribute types a value is not just a string but represents one or more references to other objects. For example the value of an mnt-by attribute is a maintainer object primary key, it represent a maintainer object. For these types of attributes a value containing a colon is synonym of multiple primary keys separated by comma. This feature is also enabled in the Update Services, you can specify multiple comma separated values in your attribute elements but these values will be normalized during the request processing phase and the final object will contain a separate attribute for every key and in case of a comment that was defined on an attribute with comma separated values that comment will be replicated on all the the normalized attributes.

For example if you are executing a Create or Update request and the xml that you submit contains something like:

<attribute name="mnt-by" value="GG-MNT,PP-MNT" comment="Two maintainers are better than one" />

than the the final object in the RIPE Database will contain two separate maintainer attributes each sharing the same comment and A REST lookup of this object will return an XML containing separate maintainers:

<attribute name="mnt-by" value="GG-MNT" comment="Two maintainers are better than one" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/GG-MNT"/>
</attribute>
<attribute name="mnt-by" value="PP-MNT" comment="Two maintainers are better than one" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/pp-mnt"/>
</attribute>

Anyway, unless you really want to replicate the same comment on all normalized attributes, there is no reason to use this feature, it should be easier for you to create a separate attribute for every separate value. We added the feature just because it came out of the box from the work that we did to normalize RPSL objects in the Query Services.

The input XML required from the Modify interfaces must use a different schema because it needs to describe an action to be applied to an object, not the object itself. This schema is described in the paragraphs specific to the Modify interfaces.

The HTTP methods, aka REST verbs

The Update  Services are exposed on the PUT, POST and DELETE method. The mapping between different services and methods has been carefully chosen following the REST paradigm, considering the RIPE Database objects as resources exposed via HTTP (RFC2616).

The resulting mapping is:

HTTP Method Services
PUT Update
POST Create, Modify
DELETE Delete

HTTP Request and HTTP Response

In the previous two paragraphs we have discussed all the details of the XML schema and also the HTTP methods that you should use to prepare a valid HTTP request.

We only need to say something about content negotiation and expected responses.

The delete service doesn't require any XML content to be sent. It can be invoked with a DELETE request on an appropriate URL and nothing else. A response to a successful delete will contain an HTTP status code of "204 No Content" and an empty body.

The Create, Update and Modify services require clients to send an XML in the request body. For this reason the clients must set a request header "content-type: application/xml".

A successful Create response will contain a status code of "201 Created" and a Location header containing the Lookup Service URL for the new resource in the RIPE Database. If you created a person or role specifying an AUTO-n nic-hdl than the lookup URL in the Location header will show the nic-hdl that has been generated in the Whois Database. If you need it you can extract it from there or just execute a lookup with that URL and fetch your new object.

Successful Update and Modify requests return a "200 OK" status code and a body containing the updated object in its entirety.

The Error Codes

The possible error codes are:
Status Code Reasons Notes
Bad Request (400) The request has a malformed syntax or contains invalid parameters The body may contain a specific error message or the entire Whois response text
Unauthorized (401) The provided credentials are not correct (wrong password) or the specified maintainer is not authorized to change the given object
Not Found (404) The object that you are trying to delete, update or modify doesn't exist
Method Not Allowed (405) The request was sent using an HTTP method that is not valid for the given URL The response will include an "Allow" header with a list of valid HTTP methods for the requested resource
Conflict (409) The request couldn't be accepted because some integrity constraint was violated
Internal Server Error (500) An unexpected system error occurred

The most frequent reasons for a Conflict 409 status code are described in the following table:

Service Violated Constraint
UPDATE The person/role attribute in a person/role object cannot be changed
DELETE The object is referenced from other objects
CREATE One of this object's attributes contains a key to an object that doesn't exist
CREATE An object with the requested nic-hdl already exists
CREATE The requested nic-hdl is not available because an object with that nic-hdl existed in the past

The REST API specification for the Update Services

The current version of the RIPE Database REST Update API exposes the following methods.

[Service URL] = https://apps.db.ripe.net/whois

Service interface HTTP URL HTTP Method HTTP GET Parameters
create [Service URL]/create POST password ..*
update [Service URL]/update/{source} /{object-type}/{primary-key} PUT password ..*
delete [Service URL]/delete/{source}/{object-type}/{primary-key} DELETE password ..*
modify [Service URL]/modify/{source}/{object-type}/{primary-key} POST

password ..*

create

A successful create request creates an object in the RIPE Database or in the RIPE Test Database, depending on the source that you specify in the source element of your request XML. Source can be "ripe" or "test".

One or more password values can be specified as HTTP parameters.

The create interface is accessible using the HTTP POST method. The request must include a 'content-type: application/xml' header because your request body will contain an XML document describing the new object and the target source.

An example of XML object:
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources>
<objects>
<object type="person">
<source id="test"/>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="Singel 258"/>
<attribute name="phone" value="+31-1234567890"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="mnt-by" value="PP-MNT" />
<attribute name="nic-hdl" value="AUTO-1" />
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="source" value="TEST"/>
</attributes>
</object>
</objects>
</whois-resources>

An example of create request using the CURL command:

curl -X POST -H 'Content-Type: application/xml' -d '<whois-resources><objects>
<object-type="person"><source-id="test"/><attributes>
<attribute name="person" value="Pauleth Palthen"/><attribute name="address" value="Singel 258"/>
<attribute name="phone" value="+31-1234567890"/><attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="mnt-by" value="PP-MNT" /><attribute name="nic-hdl" value="AUTO-1" />
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/><attribute name="source" value="TEST"/>
</attributes></object></objects></whois-resources>' 
https://apps.db.ripe.net/whois/create?password=123 -D headers.txt

The HTTP headers for a success response:

HTTP/1.1 201 Created
Date: Tue, 28 Dec 2010 14:17:28 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Location: http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST
Content-Length: 0
Connection: close
Content-Type: text/plain; charset=UTF-8

The response body will be empty.

update

A successful update request replaces all of an object attributes with the new set of attributes described in the request. The target database can be ripe or test and is specified with the source element in the XML document sent with the request.

One or more password values can be specified as HTTP parameters.

The update interface is accessible using the HTTP PUT method. The request must include a 'content-type: application/xml' header because your request body will contain an XML document describing the object update and the target source.

An example of XML object:
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources>
<objects>
<object type="person">
<source id="test"/>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="Singel 123"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="mnt-by" value="PP-MNT" />
<attribute name="nic-hdl" value="PP16-TEST" />
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="source" value="TEST"/>
</attributes>
</object>
</objects>
</whois-resources>

An example of update request using the CURL command:

curl -X PUT -H 'Content-Type: application/xml' -d '<whois-resources><objects>
<object-type="person"><source-id="test"/><attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="Singel 123"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="mnt-by" value="PP-MNT" />
<attribute name="nic-hdl" value="PP16-TEST" />
<attribute name="source" value="TEST"/></attributes></object></objects></whois-resources>' 
https://apps.db.ripe.net/whois/update/test/person/pp16-test?password=123 -D headers.txt

The HTTP headers for a success response:

HTTP/1.1 200 OK
Date: Tue, 28 Dec 2010 15:24:35 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Connection: close
Transfer-Encoding: chunked
Content-Type: application/xml 

The response body for a success response:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources service="lookup" xmlns:xlink="http://www.w3.org/1999/xlink">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP3-TEST"/>
<objects>
<object type="person">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<source id="test"/>
<primary-key>
<attribute name="nic-hdl" value="PP16-TEST"/>
</primary-key>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="Singel 123"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="mnt-by" value="PP-MNT" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/PP-MNT"/>
</attribute>
<attribute name="nic-hdl" value="PP16-TEST"/>
<attribute name="source" value="TEST"/>
</attributes>
</object>
</objects>

delete

A successful delete request deletes an object from the RIPE Database or the RIPE Test Database. The target database for the delete service is specified directly as a URL parameter as well as the primary key and the object type of the object to be deleted.

In practice the interface protocol is the same of a lookup request, but the the final intent of this lookup is the object deletion.

One or more password values can be specified as HTTP parameters. Another optional HTTP parameter is "reason". The "reason" can be used to submit a string that describes a motivation for this deletion.

The HTTP Request body must be empty.

The delete interface is accessible using the HTTP DELETE method. The request doesn't need to include any specific header.

An example of delete request using the CURL command:

curl -X DELETE https://apps.db.ripe.net/whois/delete/test/person/pp16-test?password=123 -D headers.txt

The HTTP headers for a success response:

HTTP/1.1 204 No Content
Date: Wed, 29 Dec 2010 09:43:17 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Content-Length: 0
Connection: close
Content-Type: text/plain; charset=UTF-8

modify

The modify interface implements complex object manipulations that would otherwise require multiple client side operations, like:

  • querying the Whois Database,
  • filtering from the query response the only object that need to be modified,
  • parsing the object RPSL (handling all the intricacies of RPSL),
  • modifying specific attributes,
  • submitting the edited object.

With the modify interface this error prone processing of objects can be replaced with just one simple request since it is implemented in the service back-end, one only centralized point of maintenance.

A client just needs to specify the type of operation to be applied, the primary key of an object and eventually a set of attributes.

The modify interface, like the delete, is based on the same protocol of a lookup. The URL specifies the target source, the object type and the primary key of the object to be modified. The source can be "ripe" for the RIPE Database or "test" for the RIPE Test Database:

https://apps.db.ripe.net/whois/modify/<source>/<object-type>/<primary-key>?password=...

The HTTP method must be POST and the request must include a "content-type: application/xml" header.

In this release we support three main operations on object attributes: 'replace', 'add' and 'remove'.

Important, a modify request succeeds only if the final modified object satisfies the RPSL specification. For example a modify request that generate an object missing mandatory attributes will obviously fail because such an object would be invalid.

Let's see the different actions that actually can be executed with the three basic operations:

replace attributes

A replace request replaces all the attributes of a given type with a new set of attributes, not necessarily of the same type.

The attribute-type attribute in the replace element specifies what type of attribute will be subject of the replacement action.

A valid XML document that describes a replace operation on attributes of type address is:

<whois-modify>
<replace attribute-type="address">
<attributes>
<attribute name="address" value="RIPE Network Coordination Centre (NCC)"/>
<attribute name="address" value="P.O. Box 10096"/>
<attribute name="address" value="1001 EB Amsterdam"/>
<attribute name="address" value="The Netherlands"/>
<attribute name="remarks" value="This is our new address!"/>
</attributes>
</replace>
</whois-modify>

An example of replace attributes using the CURL command:

curl -X POST -H 'Content-Type: application/xml' -d 
'<whois-modify><replace attribute-type="address"><attributes>
<attribute name="address" value="RIPE Network Coordination Centre (NCC)"/>
<attribute name="address" value="P.O. Box 10096"/>
<attribute name="address" value="1001 EB Amsterdam"/>
<attribute name="address" value="The Netherlands"/>
<attribute name="remarks" value="This is our new address!"/>
</attributes></replace></whois-modify>'
https://apps.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt

The response body may be:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources service="lookup" xmlns:xlink="http://www.w3.org/1999/xlink">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<objects>
<object type="person">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<source id="test"/>
<primary-key>
<attribute name="nic-hdl" value="PP16-TEST"/>
</primary-key>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="RIPE Network Coordination Centre (NCC)"/>
<attribute name="address" value="P.O. Box 10096"/>
<attribute name="address" value="1001 EB Amsterdam"/>
<attribute name="address" value="The Netherlands"/>
<attribute name="remarks" value="This is our new address!"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="mnt-by" value="PP-MNT" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/PP-MNT"/>
</attribute>
<attribute name="nic-hdl" value="PP16-TEST"/>
<attribute name="source" value="TEST"/>
</attributes>
</object>
</objects>
</whois-resources>

The response headers:

HTTP/1.1 200 OK
Date: Wed, 29 Dec 2010 10:40:27 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Connection: close
Transfer-Encoding: chunked
Content-Type: application/xml

append new attributes

An append request will just append a new set of attributes to an existing object.

A valid XML document that describes an append for two new attributes, a phone and a fax-no:

<whois-modify>
<add>
<attributes>
<attribute name="phone" value="+31 20 535 4444"/>
<attribute name="fax-no" value="+31 20 535 4445"/>
</attributes>
</add>
</whois-modify>

An example of append attributes using the CURL command:

curl -X POST -H 'Content-Type: application/xml' -d 
'<whois-modify><add><attributes><attribute name="phone" value="+31 20 535 4444"/>
<attribute name="fax-no" value="+31 20 535 4445"/></attributes></add></whois-modify>'
https://apps.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt

The response body may be:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources service="lookup" xmlns:xlink="http://www.w3.org/1999/xlink">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<objects>
<object type="person">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<source id="test"/>
<primary-key>
<attribute name="nic-hdl" value="PP16-TEST"/>
</primary-key>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="RIPE Network Coordination Centre (NCC)"/>
<attribute name="address" value="P.O. Box 10096"/>
<attribute name="address" value="1001 EB Amsterdam"/>
<attribute name="address" value="The Netherlands"/>
<attribute name="remarks" value="This is our new address!"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="mnt-by" value="PP-MNT" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/PP-MNT"/>
</attribute>
<attribute name="nic-hdl" value="PP16-TEST"/>
<attribute name="source" value="TEST"/>
<attribute name="phone" value="+31 20 535 4444"/>
<attribute name="fax-no" value="+31 20 535 4445"/>
</attributes>
</object>
</objects>
</whois-resources>

The response headers:

HTTP/1.1 200 OK
Date: Wed, 29 Dec 2010 10:40:27 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Connection: close
Transfer-Encoding: chunked
Content-Type: application/xml

add new attributes starting from the line at index N

An add attributes from line at index N will inject new attributes starting from the given index. All the attributes that were originally positioned at indexes M>=N will be shifted down to M+X, where X is the number of attributes being added.

Attribute indexes start from 0.

A valid XML document that describes a request to add two remarks starting from index 6:

<whois-modify>
<add index="6">
<attributes>
<attribute name="remarks" value="These remark lines will be added"/>
<attribute name="remarks" value="starting from index 6 (line 7) !"/>
</attributes>
</add>
</whois-modify>

An example of add new attributes using the CURL command:

curl -X POST -H 'Content-Type: application/xml' -d '<whois-modify><add index="6">
<attributes><attribute name="remarks" value="These remark lines were just added"/>
<attribute name="remarks" value="below the 6th attribute (at line 7) !"/>
</attributes></add></whois-modify>' 
https://apps.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt

The response body may be:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources service="lookup" xmlns:xlink="http://www.w3.org/1999/xlink">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<objects>
<object type="person">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<source id="test"/>
<primary-key>
<attribute name="nic-hdl" value="PP16-TEST"/>
</primary-key>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="RIPE Network Coordination Centre (NCC)"/>
<attribute name="address" value="P.O. Box 10096"/>
<attribute name="address" value="1001 EB Amsterdam"/>
<attribute name="address" value="The Netherlands"/>
<attribute name="remarks" value="This is our new address!"/>
<attribute name="remarks" value="These remark lines were just added"/>
<attribute name="remarks" value="This remark was originally at index 6 (line 7)!"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="mnt-by" value="PP-MNT" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/PP-MNT"/>
</attribute>
<attribute name="nic-hdl" value="PP16-TEST"/>
<attribute name="source" value="TEST"/>
<attribute name="phone" value="+31 20 535 4444"/>
<attribute name="fax-no" value="+31 20 535 4445"/>
</attributes>
</object>
</objects>
</whois-resources>

The response headers may be:

HTTP/1.1 200 OK
Date: Wed, 29 Dec 2010 11:02:30 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Connection: close
Transfer-Encoding: chunked
Content-Type: application/xml

remove all attributes of a given type

This action is very simple, will just remove all the attributes of a given type, independently from their positioning or distribution within the object. It is important to note that this operation may cause most attribute indexes to change since attributes of the type to be removed may be scattered all over the object.

A valid XML document:

<whois-modify>
<remove attribute-type="remarks"/>
</whois-modify>

An example of remove attributes using the CURL command:

curl -X POST -H 'Content-Type: application/xml' -d 
'<whois-modify><remove attribute-type="remarks"/></whois-modify>' 
https://apps.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt

The response body may be:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources service="lookup" xmlns:xlink="http://www.w3.org/1999/xlink">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<objects>
<object type="person">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<source id="test"/>
<primary-key>
<attribute name="nic-hdl" value="PP16-TEST"/>
</primary-key>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="RIPE Network Coordination Centre (NCC)"/>
<attribute name="address" value="P.O. Box 10096"/>
<attribute name="address" value="1001 EB Amsterdam"/>
<attribute name="address" value="The Netherlands"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="e-mail" value="ppalse _at_ ripe _dot_ net"/>
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="mnt-by" value="PP-MNT" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/PP-MNT"/>
</attribute>
<attribute name="nic-hdl" value="PP16-TEST"/>
<attribute name="source" value="TEST"/>
<attribute name="phone" value="+31 20 535 4444"/>
<attribute name="fax-no" value="+31 20 535 4445"/>
</attributes>
</object>
</objects>
</whois-resources>

The response headers may be:

HTTP/1.1 200 OK
Date: Wed, 29 Dec 2010 11:06:43 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Connection: close
Transfer-Encoding: chunked
Content-Type: application/xml

remove the Nth attribute

This action will just remove the one attribute that is positioned at index N. Remember that the indexing starts from 0. Index of all attributes positioned at M>N+1 will be decreased by 1.

A valid XML document:

<whois-modify>
<remove index="6"/>
</whois-modify>

An example of remove Nth attribute using the CURL command:

curl -X POST -H 'Content-Type: application/xml' -d 
'<whois-modify><remove index="6"/></whois-modify>' 
https://apps.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt

The response body may be:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources service="lookup" xmlns:xlink="http://www.w3.org/1999/xlink">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<objects>
<object type="person">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/person/PP16-TEST"/>
<source id="test"/>
<primary-key>
<attribute name="nic-hdl" value="PP16-TEST"/>
</primary-key>
<attributes>
<attribute name="person" value="Pauleth Palthen"/>
<attribute name="address" value="RIPE Network Coordination Centre (NCC)"/>
<attribute name="address" value="P.O. Box 10096"/>
<attribute name="address" value="1001 EB Amsterdam"/>
<attribute name="address" value="The Netherlands"/>
<attribute name="phone" value="+31-0987654321"/>
<attribute name="changed" value="ppalse _at_ ripe _dot_ net 20101228"/>
<attribute name="mnt-by" value="PP-MNT" referenced-type="mntner">
<link xlink:type="locator" xlink:href="http://apps.db.ripe.net/whois/lookup/test/mntner/PP-MNT"/>
</attribute>
<attribute name="nic-hdl" value="PP16-TEST"/>
<attribute name="source" value="TEST"/>
<attribute name="phone" value="+31 20 535 4444"/>
<attribute name="fax-no" value="+31 20 535 4445"/>
</attributes>
</object>
</objects>
</whois-resources>

The response headers may be:

HTTP/1.1 200 OK
Date: Wed, 29 Dec 2010 11:06:43 GMT
Server: Apache/2.2.3 (CentOS)
X-Powered-By: Servlet 2.5; JBoss-5.0/JBossWeb-2.1
Connection: close
Transfer-Encoding: chunked
Content-Type: application/xml

 

apps.db.ripe.net

44 Comments

hroi
hroi says:
Feb 18, 2011 01:25 AM
I've been playing with the API tonight, working on a tool to generate prefix lists like RtConfig does.
Comparing outputs between my code and RtConfig, I stumbled on a discrepancy in the outputs from the REST API and the whois web interface.

Compare the returned routes from

http://lab.db.ripe.net/whoi[…]mp;inverse-attribute=origin

with

http://www.db.ripe.net/whoi[…]=RIPE&object_type=route

You will see that 46.46.192.0/19 amongst others is missing from the returned data from the REST API.

The route is definitely there: http://lab.db.ripe.net/[…]/AS2116

Am I missing something?
hroi
hroi says:
Feb 18, 2011 02:05 AM
prefixes.core> (count (fetch-routes "AS2116"))
100

I now realize exactly 100 objects are returned, where 108 objects exist. It see there is a limit set up from a previous article.

I may not have understood the purpose of the API. The Terms and Conditions for access to data (https://labs.ripe.net/datarepository/conditions/basic) indicates that access is for research purposes only. Will the REST API be released for operational use?
bfiorell
bfiorell says:
Feb 18, 2011 11:07 AM
Dear Hroi,
 
Yes, we are applying this constraint of 100 maximum objects per query. I will add it to this document, it was only mentioned in one of our previous articles. The reason for the constraint is that the Whois Server actually doesn't have any limit in terms of response size so there are queries that may return thousands of objects.These web services do quite a lot of parsing and processing of the Whois data in order to stream normalised XML objects so the idea of an 'unlimited response size' wouldn't be sustainable.
So just to keep this point in mind we set the limit to 100 and also push users to do more selective queries.

But for specific use cases that require the processing of larger amount of objects we are willing to implement and publish ad hoc web service interfaces based on the community requirements. If you think that for the development of your tool you may take advantage of specialised web services and these services may also be useful for other concerns, then please write your feedback and requirements on the database working group mailing list.

About the Terms and Conditions, the link you are indicating is not related to the services described above, but to the RIPE Data Repository (http://labs.ripe.net/datarepository/). Our REST Services return Whois data. So, its the RIPE Database Terms and Conditions that apply (http://www.ripe.net/data-tools/support/documentation/terms). The Services themselves are in beta. But we support them and we encourage you to use them since the only way to improve them is from community feedback.

We will soon publish them on more scalable production machines but even then we will keep them in a beta status for some more time to allow a more agile development process.

Regards
--
Benedetto Fiorelli
Software Engineer
RIPE NCC Database Group
Ales
Ales says:
Jun 24, 2011 03:47 PM
Hello,
would it be possible to simultaneously update or modify multiple objects.
Lets tak for example a set of inetnum objects, which have some admin-c atribute and I would like to change that admin-c on multiple inetnums in a single REST call (I would get the set of inetnums by a GET query).
Thank you for your help,
Ales
bfiorell
bfiorell says:
Jun 24, 2011 05:22 PM
Dear Ales,

for these new update interfaces we chose to allow one object per request primarily to avoid conditions where requests could generate partial updates, that is when only a subset of the submitted objects gets successfully updated. The handling of partial updates introduces complexity in the communication protocol (in this case the response schema) because the server has to respond with details on which object updates did fail and which succeeded and why there were failure for every failed update, all in one response. The client also will need to handle a very complex response in order to take corrective actions.

On the other hand with a single object constraint it's simpler for clients to have the control of the transaction.
A client can execute as many requests as required, implementing the appropriate iteration logic and handling errors in a simple way that doesn't require complex response parsing but just a check on the HTTP status code.

If you have to modify a single attribute on multiple objects you can give a try at the modify services, for example there is a replace attributes service that will let you replace attributes by just providing primary key and object type, without having to fetch and modify the entire RPSL.

But be aware that these services are still in a prototype phase,
we recommend to test them thoroughly on the TEST database.

Regards.
--
Benedetto Fiorelli
Senior Software Engineer
RIPE NCC Database Group
Ales Cadez
Ales Cadez says:
Aug 19, 2011 04:35 PM
Dear all,
I have one inet6num object, which I want to delete on:
https://lab.db.ripe.net/[…]/127

If I use the URL, which should call the delete action, I get 404 response code.

The call:
https://lab.db.ripe.net/[…]/127?password=arnes

Response I get:
HTTP Status 404 - Could not find resource for relative : /whois/delete/test/inet6num/a:b:c:d:e:f:1:0/127 of full path: https://lab.db.ripe.net/[…]/127?password=arnes

What am I missing to see? Any help would me most welcome.
Thank you,

Ales Cadez
ARNES
bfiorell
bfiorell says:
Aug 23, 2011 10:03 AM
Dear Ales,

thanks for reporting the bug, the lookup service was properly escaping the "/" character in the primary key values (that is possible in inetnum, inet6num and route objects) but the delete, update and modify services were not.
I just deployed a new version that should solve the issue, you can try again now.

Regards
--
Benedetto Fiorelli
Software Engineer
RIPE NCC Database Group
Ales Cadez
Ales Cadez says:
Sep 16, 2011 07:01 PM
I have a question regarding clean-up of RIPE test database. While testing it often happens, that objects (inetnum,mntner) are often deleted, so I have to create them again. What is the factor for object clean-up in test DB? Is there a "life-time" of an object or is there a regular test DB "total" clean-up?

thank you for your answers,
Ales Cadez
ARNES
Bogdan Dumitrescu
Bogdan Dumitrescu says:
Sep 28, 2011 09:12 AM
Dear Ales,


The RIPE Test Database gets reset to a basic set of objects at the beginning of each month.


Best regards,

Bogdan Dumitrescu
Software Engineer
RIPE NCC
Roger Kind Kristiansen
Roger Kind Kristiansen says:
Sep 29, 2011 02:12 PM
Hi guys,

Just noticed the service returns a 401 (Unauthorized) when attempting to delete a non-existing entry. I'm no HTTP expert, but wouldn't a 404 make more sense?

I can add that if I create the object before prior to the delete, I get a 204 as expected, so the authorization shouldn't be the problem here?

Or perhaps.. is this a result of the same process that returns the complete "0.0.0.0 - 255.255.255.255" block when no match is found. Thus the "Unauthorized" bit stems from me not being the maintainer of that block..?
bfiorell
bfiorell says:
Sep 29, 2011 03:02 PM
Hello Roger,
the delete service uses the same logic of the lookup service to select the object to be deleted. So your suspect is probably right, maybe your key is selecting an object that your maintainer is not authorised to manage. To verify it you can do a lookup of the key that you are specifying and see what the lookup returns.

Regards.
--
Benedetto Fiorelli
Senior Software Engineer
RIPE NCC Database Group
Roger Kind Kristiansen
Roger Kind Kristiansen says:
Sep 30, 2011 03:15 PM
Hi again,

Thanks for the quick answer, Benedetto. You were right, I need to a lookup.

Next question: Is there a particular reason why getting the data in json is not an option on an update? Would be nice to be able to use the same, json-based, logic in both cases. :-)

Cheers,
Roger
bfiorell
bfiorell says:
Oct 04, 2011 09:40 AM
Hi Roger,
the idea is to use XML as main representation format because it provides standard technologies like XSD to describe and validate data structure and technologies like XSL or XPath to manipulate and transform the data into other representation styles. For example in the Query Services we generate the JSON and HTML output styles using a server side XSL transformation of XML data and it was really easy to implement.
On the other hand using JSON as an input format for the Update Services (if that is what you mean) would require 'non standard' server side technologies to validate the JSON input, to bind JSON into objects, etc.
Without much business value since we don't see for now special value in having third party web clients centered on JSON while we see some value in letting users build JSON web clients for queries.
But if you think you have good use cases for having JSON centric interfaces you can subscribe the IETF weirds mailing list and contribute to the discussion on REST service interfaces for Whois systems:
https://www.ietf.org/mailman/listinfo/weirds

Regards,

Benedetto
Roger Kind Kristiansen
Roger Kind Kristiansen says:
Oct 04, 2011 12:34 PM
Thanks for the explanation.

I can see why you want to use XML for input for creates and updates, but I just thought it would be a nice extra service to be able to get the response in JSON. Handling JSON is a little simpler than XML and would be sufficient in my case.

Since you already have the XSL to transform the query responses, there shouldn't much of an extra cost..?
bfiorell
bfiorell says:
Oct 04, 2011 02:30 PM
I understand, the Update and Modify services return the updated object in the HTTP Body.

Yes we actually don't handle response format negotiation independently from the input format. That should not be too complex to do but we didn't think it was useful since the client must be anyway able to construct xml for his request.

And processing an XML response is not that complex as it looks. You can use XPath to consume XML and with two or three lines of XPath build domain objects out of our responses XML.
Otherwise you can use XSL, there are several XML to JSON stylesheets on internet that can be used to do that, even though there is no 'one standard way', for example this is one project:
http://code.google.com/p/xml2json-xslt/

Regards,
Benedetto Fiorelli
Roger Kind Kristiansen
Roger Kind Kristiansen says:
Oct 05, 2011 12:27 PM
Ok, I can accept that.

The real problem is just me being lazy, and having spent time on parsing the JSON, did not want to do it again for XML. :-)

Cheers,
Roger
Pål Wester
Pål Wester says:
Dec 08, 2011 04:35 PM
When trying to use the rest-api to create objects in TEST we get a HTTP 500 internal server error with "Unknown error code: 500" as message. I know the XML is well formed and validated before this happens since I get 400 bad request with message 'Error on line 14 of document : The element type "attributes" must be terminated by the matching ....' when purposely not sending well formed XML.

Also I have problems deleting:
curl -X DELETE -v 'http://lab.db.ripe.net/[…]/PP1-TEST?password=emptypassword'

returns:
< HTTP/1.1 405 Method Not Allowed
< Date: Thu, 08 Dec 2011 15:33:08 GMT
< Server: Apache/2.2.3 (CentOS)
< Allow: GET, OPTIONS, HEAD
< Content-Length: 976
< Connection: close
< Content-Type: text/html;charset=utf-8

Any pointers on how to proceed from here would be appreciated.


Regards
Pål
Pål Wester
Pål Wester says:
Dec 08, 2011 05:26 PM
I see the delete has incorrect URL. When using:
curl -X DELETE -v 'https://lab.db.ripe.net/[…]/PP1-TEST?password=emptypassword'

I get the same internal server error as when I try to update or create.

BR,
Pål
Kaveh Ranjbar
Kaveh Ranjbar says:
Dec 12, 2011 10:12 AM
Hello Pål,

Thank you for you comment, as it is announced during last RIPE Meeting, the service is now moved to our production environment and is now an official BETA Service offered by RIPE NCC, that's why the lab.db.ripe.net version is deprecated and the BETA runs on apps.db.ripe.net

Everything should work fine if you point to apps server instead of labs. I will make sure the documentation is updated to reflect that as well.

Kind Regards,
Kaveh Ranjbar
Database Group Manager, RIPE NCC
Pål Wester
Pål Wester says:
Dec 13, 2011 11:27 AM
Seems like SSL2 is turned off in apps.db.ripe.net so causing the error:
curl: (35) error:14077458:SSL routines:SSL23_GET_SERVER_HELLO:reason(1112)

A workaround is forcing protocol version 3 by adding switch -3 to curl or curl_setopt($resource, CURLOPT_SSLVERSION, 3) for php5-curl.

Br
Pål
Aleš Čadež
Aleš Čadež says:
Dec 29, 2011 09:39 AM
Hello, is there something wrong with API since yesterday (28.12.2011) I'm getting 500 response error for every update call to the https?
Kaveh Ranjbar
Kaveh Ranjbar says:
Dec 29, 2011 11:35 AM
Are you using apps.db.ripe.net as your service endpoint? Testing from here everything seems to be fine. If yes, please let us know which API Call(s) produces the 500?
José Valentín Gutiérrez
José Valentín Gutiérrez says:
Jan 25, 2012 10:31 AM
Querying afrinic (source=afrinic) returns "Connection reset" since last week.
Kaveh Ranjbar
Kaveh Ranjbar says:
Jan 25, 2012 11:44 AM
Hello,

Please use our grs-source feature for any query soure other than RIPE Database. Sending proxy request to other sources is very limited, but on the GRS you can query all other RIRs as well as RADB and JPIRR.

Regards,
Kaveh Ranjbar
Database Group Manager, RIPE NCC
José Valentín Gutiérrez
José Valentín Gutiérrez says:
Feb 03, 2012 12:36 PM
There isn't available a GRS source for Afrinic
Kaveh Ranjbar
Kaveh Ranjbar says:
Feb 03, 2012 02:31 PM
Hello,

Afrinic source is available as other GRS Sources and its name name is afrinic-grs, for example this query:
http://apps.db.ripe.net/[…]/0

The name was not listed in documentation but now it is mentioned there as well.

Kind Regards,
Kaveh.
Senthil
Senthil says:
Feb 03, 2012 02:21 PM
Hi
How to pass the password in URL,if a ripe service is having more than one password. Kindly advice.

BR
Senthil
Kaveh Ranjbar
Kaveh Ranjbar says:
Feb 03, 2012 02:36 PM
Hi,

In case multiple auth. lines are listed on a maintainer object, for editing objects protected by that maintainer it is enough to authenticate with only one of those auth. methods, the logic for RIPE Database authentication has always been based on "OR".

Kind Regards,
Kaveh.
Gokul
Gokul says:
Feb 03, 2012 03:58 PM
Hi,

We are trying to reach the Ripe database(who is) using the following URl currently for testing as mentioned in the RIPE documentation.

https://apps.db.ripe.net/whois/create?password=value1

This works!

But production requires two passwords given to us already , pls let us know how you can pass both the passwords using the above command.

We cant test this because its production but pls let us know if this will work.

https://apps.db.ripe.net/[…]/create?password=value1?password=value2

Any help will be appreciated.

Thanks
Gokul
Kaveh Ranjbar
Kaveh Ranjbar says:
Feb 03, 2012 04:11 PM
Hello,

a) please check if you really have to submit both passwords because in most of the cases one password is enough as it is mentioned in reply to the previous comment.

b) In case of double auth. requirements, for example a route object which needs auth. from AUT-NUM as well as INET(6)NUM you example with two password keys should work, it is also mentioned in this API Guide (One or more password values can be specified as HTTP parameters.). More details on double authentication requirements can be found in http://www.ripe.net/[…]/getting-started and http://www.ripe.net/data-tools/db/faq/faq-route-object

c) RIPE TEST source is a sandbox environment and you should be able to reproduce your scenario there. You can create all required objects in the test database using https://apps.db.ripe.net/webupdates/ and then run your API test against your own objects.

Kind Regards,
Kaveh.
Benjamin Peter
Benjamin Peter says:
May 03, 2012 10:54 AM
Hi there

First of all, many thanks for the new API, it works great and we already use it for queries. For the past years, we used "Syncupdate" (http://syncupdates.db.ripe.net/) to create, read and edit RIPE records. It used PGP signed messages for authentication and we created many objects with the same maintainer Handle. For the future, we would like to use the new API to maintain our existing RIPE objects. But this seems to be not possible because we cannot use the password authentication described in this document.

Can you please tell us how to edit existing objects using the new API? Or is it possible to use the PGP signature paradigma for the new API?

Many thanks for your help.

Benjamin
(BS1173-RIPE)
Mirjam Kühne
Mirjam Kühne says:
May 03, 2012 04:59 PM
Thank you very much for your comment. PGP is not supported in our Update API. PGP is designed for email and we mainly use it for our email updates. For sync. updates, you can currently use PGP but since all the communication happens through HTTPS, using a password should provide the same level of communication security; specially now that we don't publish the MD5 hash of the password.

We are working on a proposal to the community to integrate RIPE Access authentication with the RIPE Database. If it gets accepted by the community, you should be able to use X.509 or passwords to use the API.
Niranjan Yalisetty
Niranjan Yalisetty says:
May 10, 2012 12:20 AM
Thanks, the documentation is descriptive. Where can I find the XSDs of the RIPE webservices? I am able to get the whois-resources XSD from http://apps.db.ripe.net/whois/xsd/whois-resources.xsd . But where can I get the XSD for <whois-modify> ? Is there URI exposed from where I can download the XSDs?
Ed Shryane
Ed Shryane says:
May 10, 2012 11:01 AM
Hi Niranjan,

Thanks for your comment. There is no schema for the whois-modify request xml, as the format is very simple (only add, remove, and replace operations are supported). The Modify section (see above) includes examples of each of these operations.

The whois-resources.xsd can be used to validate the modify response body.

Regards,

Ed Shryane,
Software Engineer, RIPE NCC.
Niranjan Yalisetty
Niranjan Yalisetty says:
May 13, 2012 07:47 PM
Hi Thanks For the Reply,

As suggested by the guide I have created person & maintainer object as Niranjan Prasad Yalisetty & NY7906-MNT respectively. I have tried creating an inetnum object using the firefox pluging and the password supplied to me by RIPE, but I am getting unauthorized error? What I did wrong? I am creating the inetnet in TEST database and the details are below,

URL: https://apps.db.ripe.net/whois/create?password=qwer1234#

Payload using HTTP POST is,
<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<whois-resources>
  <objects>
    <object type="inetnum">
      <source id="test"/>
      <attributes>
        <attribute name="inetnum" value="90.206.86.40 - 90.206.86.48"/>
        <attribute name="netname" value="Sample-Test"/>
        <attribute name="descr" value="Sample"/>
        <attribute name="remarks" value="Sample"/>
        <attribute name="country" value="GB"/>
        <attribute name="admin-c" value="NPY1-TEST"/>
        <attribute name="tech-c" value="NPY1-TEST"/>
        <attribute name="status" value="ASSIGNED PA"/>
        <attribute name="mnt-by" value="TEST-ROOT-MNT"/>
        <attribute name="mnt-lower" value="TEST-DBM-MNT"/>
        <attribute name="changed" value="niranjan.p.yalisetty@bt.com 20120513"/>
        <attribute name="source" value="TEST"/>
      </attributes>
    </object>
  </objects>
</whois-resources>

Can you please me? What am I doing wrong here. I am supplying the correct password.

Regards,
Niranjan
Kaveh Ranjbar
Kaveh Ranjbar says:
May 15, 2012 11:06 AM
Hello Niranjan,

I think it is actually an authentication issue. If you are using the test database, you have to use test database's authentication which are different from the production database. Two good starting points are http://www.ripe.net/data-tools/db/ripe-test-database and http://www.ripe.net/[…]/ripe-database-user-manual-getting-started

I would suggest testing your update first through webupdates or sync. updates and making sure everything works there, then try with API.

Our database support ticketized account is reachable via ripe-dbm.at.ripe.net

Kind Regards,
Kaveh.

---
Kaveh Ranjbar,
RIPE NCC Database Group Manager
Sylwester
Sylwester says:
May 18, 2012 04:16 PM
I have stumbled upon a problem when deleting objects.

If the objects have an address which includes non us-ascii the rest-api fetch the object and uses this AFTER converting it to utf-8. The error text is "***Error: This does not exactly match the object stored in the database.". Since we do not send any object but the key it is impossible to delete tyhe following object without changing it first.

* Failed deleting inetnum 193.69.114.32 - 193.69.114.39
  
 - From-Host: 193.69.2.46
 - Date/Time: Fri May 18 15:02:18 2012


SUMMARY OF UPDATE:

Number of objects found: 1
Number of objects processed successfully: 0
  Create: 0
  Modify: 0
  Delete: 0
  No Operation: 0
Number of objects processed with errors: 1
  Create: 0
  Modify: 0
  Delete: 1
  Syntax Errors: 0


DETAILED EXPLANATION:

      
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following object(s) were found to have ERRORS:
      

---
Delete FAILED: [inetnum] 193.69.114.32 - 193.69.114.39
***Info: Syntax check passed
  
inetnum: 193.69.114.32 - 193.69.114.39
netname: FW-LINK1-BODO
descr: Firewall link 1, Bod...
country: NO
admin-c: CCN1-RIPE
tech-c: CCN1-RIPE
status: ASSIGNED PA
mnt-by: AS2116-MNT
changed: hostmaster@ventelo.no 20081030
source: RIPE
delete: --
***Error: This does not exactly match the object stored in the database.
Kaveh Ranjbar
Kaveh Ranjbar says:
May 21, 2012 01:24 PM
Hello Sylwester,

Thank you for your comment, since this is a user specific issue and there might be user specific data involved, I think it would be better to follow it up over our ticketized support system accessible at ripe-dbm.at.ripe.net. Please kindly sned us an email to the mentioned address and give us full details on how you are sending the request and we will get back to you.
Marco Marzetti
Marco Marzetti says:
Jun 11, 2012 01:56 PM
Hello,

You should warn the user when you ban him instead of silently blacklist his IP address.
Also, when an address is blacklisted, the interface returns this error "The query didn't return any object on any of the sources that you specified: [ripe]" when the users calls the search method.

Thank You
Kaveh Ranjbar
Kaveh Ranjbar says:
Jun 11, 2012 02:10 PM
Thank you for your comment. On the command line interface, clear messages are shown when the user has reached their access limits as defined in http://www.ripe.net/data-tools/support/documentation/aup
However on the web interface, the access limit error message is not shown properly. We are aware of the problem and will implement a fix shortly.

Again thank you for your feedback.

Kind Regards,
Kaveh.

---
Kaveh Ranjbar,
RIPE NCC Database Group Manager
Marco Felice
Marco Felice says:
Aug 30, 2012 03:39 PM
Hello,

I tried to create a person object over the https Ripe's interface going with the following XML code:

<whois-resources>
    <objects>
        <object type="person">
            <source id="test"/>
            <attributes>
                <attribute name="person" value="Pauleth Palthen Example"/>
                <attribute name="address" value="Singel 258 Example"/>
                <attribute name="nic-hdl" value="PPE1-TEST"/>
                <attribute name="phone" value="+31-12341234"/>
                <attribute name="e-mail" value="pxample@ripe.net"/>
                <attribute name="mnt-by" value="MNT2012-TEST"/>
                <attribute name="changed" value="pxample@ripe.net"/>
                <attribute name="source" value="TEST"/>
            </attributes>
        </object>
    </objects>
</whois-resources>

but Ripe's interface always replais me with 401 Unauthorized, even if I have just created the mntner MNT2012-TEST just few hours ago on TEST environment.

Where do I do wrong?

Thank you all in advance.

Marco
Ed Shryane
Ed Shryane says:
Aug 31, 2012 10:35 AM
Hi Marco,

you need to authenticate as the maintainer using a password parameter in the POST URL, for example:

http://apps.db.ripe.net/[…]/PPE1-TEST?password=XXX

Regards,
Ed Shryane
RIPE NCC
Razvan Ologeanu
Razvan Ologeanu says:
Jan 21, 2014 11:45 AM
Hi there,

First of all thank you for all your great work.

I have an issue with accessing whois data for IP 172.245.62.160. This is the query:

https://rest.db.ripe.net/se[…]irr-grs&source=radb-grs

I receive this:

remarks: ****************************
remarks: * THIS OBJECT IS MODIFIED
remarks: * Please note that all data that is generally regarded as personal
remarks: * data has been removed from this object.
remarks: * To view the original object, please query the ARIN Database at:
remarks: * http://www.arin.net/
remarks: ****************************

So I'm missing a lot of data, for example the country information.

I can see all information accessing the ARIN Api - http://whois.arin.net/rest/net/NET-172-245-0-0-1/pft, but I want to know if it's possible to get all this information from RIPE WhoIs Api. Should I use optional flags or any other parametters?

I'm waiting for your answer, thanks a lot!
Ed Shryane
Ed Shryane says:
Jan 21, 2014 06:19 PM
Hi Razvan,

thank you for your comment.

The RIPE REST API allows lookup of resources across all RIRs, but the non-RIPE data is mirrored from the authoritative RIR. This data is filtered on import (all data that is generally regarded as personal data has been removed), so there is no more data for the API to return. You have to query the authoritative RIR for the original object data (which is ARIN as you mentioned).

You can however retrieve full object details for (non-mirrored) resources in the RIPE database, using the "no filtering" flag (--no-filtering or -B). For example using the REST API:

https://rest.db.ripe.net/se[…]ing=193.0.10.0&flags=rB

Please also be aware that this page documents the deprecated beta REST API, and is completely out of date. The current REST API is documented here: https://github.com/RIPE-NCC/whois/wiki/WHOIS-REST-API

Regards,
Ed Shryane
RIPE NCC
Add comment

You can add a comment by filling out the form below. Only plain text is possible. Web and email addresses will be transformed into clickable links. Comments are moderated so they won't appear immediately.