Database API

RIPE Database REST API Documentation

47

This is deprecated information and should not be used for reference.




Note that this article is not up to date anymore. Please refer to the most up-to-date RIPE Database documentation .

 

RIPE Database RESTful Web Services, the API

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.

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

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.

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 of query-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
  • l acnic-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@ripe.net " />
<attribute name= "mnt-by" value= "PP-MNT" />
<attribute name= "nic-hdl" value= "AUTO-1" />
<attribute name= "changed" value= " ppalse@ripe.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@ripe.net " />
<attribute name= "mnt-by" value= "PP-MNT" />
<attribute name= "nic-hdl" value= "AUTO-1" />
<attribute name= "changed" value= " ppalse@ripe.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@ripe.net
 "/>
<attribute name="mnt-by" value="PP-MNT" /><attribute name="nic-hdl" value="AUTO-1" />
<attribute name="changed" value="
 ppalse@ripe.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@ripe.net " />
<attribute name= "mnt-by" value= "PP-MNT" />
<attribute name= "nic-hdl" value= "PP16-TEST" />
<attribute name= "changed" value= " ppalse@ripe.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@ripe.net
   "/>
<attribute name="changed" value="
   ppalse@ripe.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@ripe.net " />
<attribute name= "changed" value= " ppalse@ripe.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@ripe.net " />
<attribute name= "changed" value= " ppalse@ripe.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@ripe.net " />
<attribute name= "changed" value= " ppalse@ripe.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@ripe.net "/>
<attribute name="changed" value=" ppalse@ripe.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@ripe.net "/>
<attribute name="changed" value=" ppalse@ripe.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@ripe.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

Tags:
47

About the author

Comments 47