When we started developing the RIPE Database API and the accompanying RESTful web services, we first implemented the "Read" service. The RESTful web services now also support Create, Update and Delete functionalities. Not only did we implement these methods, but we also introduced some workflow refinements that should make programmatic interaction with the RIPE Database much easier, taking away some of the common aches of the way the legacy "Mail" and "Sync" update interfaces work.
Note that this article is not up to date anymore. Please refer to the most up-to-date RIPE Database documentation .
Introduction
CRUD is an acronym for C reate, R ead, U pdate and D elete. When we started developing the RIPE Database API and the accompanying RESTful web services we first implemented the "Read" service. The RESTful web services now also support Create, Update and Delete functionalities. Not only did we implement these methods, but we also introduced some workflow refinements that should make programmatic interaction with the RIPE Database much easier, taking away some of the common aches of the way the legacy "Mail" and "Sync" update interfaces work.
On top of the regular CRUD functionality, we have also implemented some advanced object manipulation "use cases" in the form of a Modify web service. The Modify service will hopefully take away from new database clients the need for RPSL parsing that is commonly error prone and replicated in a multitude of incomplete client libraries.
Target audience
We would like to start by setting the right expectations for the target audience of this article. This article will be of interest to you if:
- you are interested in experiment REST as a new service oriented way to interact with the RIPE Database.
- you have used the RESTful Query API for the RIPE Database and want to do more.
- you are planning to do, or you already do, any kind of programming against the RIPE Database, using the most accessible protocol nowadays, HTTP.
- you are technically minded and interested in our approach for developing RESTful Web Services on top of a 10 year old legacy system.
- you want to review and contribute to the design of new RIPE Database interfaces.
For the less technical, regular users of the RIPE Database we also have good news. The API described in this article will be used to develop better and easier ways to work with the RIPE Database. This article may be of interest to you too even if it is a bit technical...
How do we use the REST verbs
We chose to adopt the following mapping between our CRUD services and the REST verbs:
| Transaction | REST method |
| Create | POST |
| Read | GET |
| Update | PUT |
| Delete | DELETE |
| Modify* | POST |
* Modify is our use case oriented object manipulation service
The verbs have been selected considering the different natures of every different service. The HTTP protocol methods GET, PUT and DELETE are supposed to be idempotent, which means that a GET, PUT or DELETE request will generate the same effect no matter how many time it is performed if the target resource is not subject to other external actions.
For example a GET request for a given resource will return always the same resource, or always return a 404 error code if the resource doesn't exist. Similarly a PUT on a resource will always replace the resource with what is being sent in the request, no matter how many time the same resource content is being PUT, exactly the same way you would expect a RIPE Database update to behave.
On the other hand a POST request doesn't need to be idempotent, the HTTP POST method is designed as the general way to send functional requests to an HTTP server.
For this reason the POST verb fits perfectly on a create service that may create a new resource with a given natural key if the key is not yet in use or may return a 409 Conflict error code if the key is already in use. A service of this kind is by its nature not idempotent since two serial executions may return different responses that a client can process in different ways. Similarly a modify API designed to manipulate subsections or attributes of a resource are naturally not idempotent since they may have different effects on the resource depending on the number of executions.
The REST service URI and testing the service
Each different RESTful web services has its own specific end point URI. For the services that operate on existing resources the URI also has the function of a resource locator:
Create
https://lab.db.ripe.net/whois/create
Update
https://lab.db.ripe.net/whois/update/<source>/<object-type>/<primary-key>
Delete
https://lab.db.ripe.net/whois/delete/<source>/<object-type>/<primary-key>
Modify
https://lab.db.ripe.net/whois/modify/<source>/<object-type>/<primary-key>
Where:
- <source> is the source database (example: ripe, test)
- <object-type> is the type of RPSL object (example: person, aut-num, inetnum etc...)
- <primary-key> is the primary key of the object (example: pp-ripe)
All the end point URI accept one or more "password" parameters. Delete also accepts an optional "reason" parameter.
Example:
https://lab.db.ripe.net/whois/create?password=abc
|
Passwords Please note that the service only works with objects that are protected with password based authentication. Objects that require purely PGP based authentication cannot be updated using the RESTful web services. |
|---|
In order to start testing the service, you will need a PERSON and MNTNER object. If you do not already have these in the TEST Database we suggest you use the Start-up service and create a new PERSON and MNTNER object pair, making sure you set "source" to be the TEST Database in the startup form. The API does also work with the RIPE Database and it will change live data, but please only use the TEST Database if you are just reviewing or testing the features of this API. All the examples in this article should work by just copying and pasting the code in a terminal window or reproducing similar test cases with your framework of choice.
If you are a command line person, "curl" can be very easy to use for a first exploration of our API and can be also the good choice to build small parametrised command line scripts.
If you prefer to test the services with a more visual interface you can install one of the many browser extensions for your browser of choice. For example we use sometimes "HTTP Resource Test" or "REST Client" Firefox add-ons.
If you are already accustomed to Web Services and software development, you may want to use more advanced test frameworks, like SoapUI or maybe directly start prototyping your own REST client in your favorite programming language. Your feedback on this topic will be more than welcome. There are REST frameworks for any development platforms but is always good to share experiences.
All the examples have been tested and executed on the TEST Database. You should just customise them using your own PERSON and MNTNER objects to avoid collisions with other users. Obviously all the REST services work with any type of object, so feel free to test them with other object types and with your specific requirements.
And of course, please contact us if you find any bug or any missing feature.
Please also remember that the RIPE Test Database is reinitialised and all test objects are removed on the first day of each month.
On to the real show!
Service requests
When using the Create, Update and Modify services, you will be streaming XML in the body of your HTTP request.
You will therefore need to set a "Content-type: application/xml" header in your HTTP request in order to negotiate the proper communication with our HTTP interfaces. This is not required for the Delete service since a Delete request has no body.
For the Create and Update services we have reused the same XML schema that we designed for the REST Query Services, the elements are the same but you don't need to specify all the details that a REST Query response would contain, for example you don't have to specify the source attribute or any link element.
In future we will publish a more detailed specification of all our schemata, but for now you can simply use the examples as templates for your experiments.
The object schema also supports advanced features that were already described in the articles for the REST Query API .
For example, you can use the "comment" attribute on any "attribute" element to generate end of line comments or you can specify comma separated values for all attribute that represent object references and they will be normalised into separate attributes.
For example if the body of a Create, Update or Modify request contains the following attribute element:
<attribute name="mnt-by" value="GG-MNT,PP-MNT" comment="Two maintainers are better than one" />
the REST service will normalise it into two separate attributes and the two attributes will share the same end of line comment, as follows:
<attribute name="mnt-by" value="GG-MNT" comment="Two maintainers are better than one" referenced-type="mntner"> <link xlink:type="locator" xlink:href="http://lab.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://lab.db.ripe.net/whois/lookup/test/mntner/pp-mnt"/> </attribute>
The latter feature lets you specify multiple attribute values per single XML element. This behaviour comes out of the box from all the work we have done to handle RPSL comma separated values in our low level API. But we are not sure if we want to support this "denormalised" representation in our future releases.
For this reason we suggest you avoid using comma seperated lists and always define only one value for every attribute element.
The final XML that you will generate this way will be a one to one representation of the normalised object that will be generated in the RIPE Database.
The Modify service uses a more process oriented schema that you will see described later in this article.
Service responses
The HTTP response will always contain a response code. The HTTP response code will be the official return message that you will have to check to verify the success or failure of the processing. We assigned different response codes to different success or failure conditions following the principles outlined by RFC 2616 (for more details you may want to consult the RFC).
The body of the HTTP response that you will receive from the services, with the exception of the Delete service, will contain an XML in case of success or an error message in case of failure.
In the case of the Create service a success response (201 Created) will also contain a special HTTP header, "Location", whose value will be the Lookup service URL of the newly created object.
In case you just created a person or role using the nic-hdl AUTO-n facility, the Location URL will contain the value of the generated nic-hdl.
Below are the most common response codes that the service uses:
HTTP/1.1 200 OK
The request was processed successfully. In the case of a POST, the response body will contain the processed object.
Example:
Header
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
Body
<?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://lab.db.ripe.net/whois/lookup/<SOURCE>/<OBJECT TYPE>/<PRIMARY KEY>"/> <objects> <object type="<OBJECT TYPE>"> <link xlink:type="locator" xlink:href="http://lab.db.ripe.net/whois/lookup/<SOURCE>/<OBJECT TYPE>/<PRIMARY KEY>"/> <source id="<SOURCE>"/> <primary-key> <attribute name="<NAME PRIMARY KEY>" value="<PRIMARY KEY>"/> </primary-key> <attributes> ... </attributes> </object> </objects>
HTTP/1.1 201 Created
The request has been successfully executed and resulted in a new object being created. The "Location" header will contain the Lookup URL for the newly created object.
Example:
Header
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://lab.db.ripe.net/whois/lookup/test/person/pp16-test Content-Length: 0 Connection: close Content-Type: text/plain; charset=UTF-8
HTTP/1.1 204 No Content
The server has fulfilled the request and does not need to return anything. This happens for instance after a successful DELETE.
Example:
Header
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
HTTP/1.1 400 Bad Request
The request could not be understood by the server due to malformed syntax or invalid parameters. The body may contain an error message or a full response text.
Example:
Header
HTTP/1.1 400 Bad Request 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
Body
- From-Host: 193.0.23.9 - Date/Time: Wed Dec 29 09:43:17 2010 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: 0 Syntax Errors: 1 DETAILED EXPLANATION: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following object(s) were found to have ERRORS: --- Update FAILED: [person] PP5-TEST Pauleth Palthen ***Error: Syntax error in object person: Pauleth Palthen phone: +31-1234567890 e-mail: ppalse@ripe.net mnt-by: PP-MNT nic-hdl: PP5-TEST changed: ppalse@ripe.net 20101228 source: TEST ***Error: Required attribute "address" is missing ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The RIPE Database is subject to Terms and Conditions: http://www.ripe.net/db/support/db-terms-conditions.pdf For assistance or clarification please contact: RIPE Database Administration < ripe-dbm@ripe.net >
HTTP/1.1 401 Unauthorized
The request was not executed because the provided credentials are not correct (wrong passwords) or because the specified maintainer is not authorised to change the given object.
Example:
Header
HTTP/1.1 401 Unauthorized 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
HTTP/1.1 405 Method Not Allowed
The HTTP method being used is not allowed for this request URL. The response will include an "Allow" header containing a list of valid methods for the requested resource.
Example:
Header
HTTP/1.1 405 Method Not Allowed Date: Wed, 29 Dec 2010 09:43:17 GMT Server: Apache/2.2.3 (CentOS) Allow: POST, OPTIONS Content-Length: 0 Connection: close Content-Type: text/html;charset=utf-8
HTTP/1.1 409 Conflict
The request could not be completed due to a conflict with the current state of the object.
We mapped "HTTP/1.1 409 Conflict" to RIPE Database referential integrity errors.
Here are some examples of RIPE Database referential integrity errors that can cause a 409 Conflict response:
- a RIPE Database integrity conflict during an HTTP request
- an UPDATE fails, because names cannot be changed on Person/Role objects
- an object cannot be deleted if it is referenced from another object
- CREATE a reference to an object that does not exist
- CREATE an object with a nic-hdl that already exists
- CREATE an object with a nic-hdl that is not available, because another object with that nic-hdl existed in the past
Example:
Header
HTTP/1.1 409 Conflict Date: Wed, 29 Dec 2010 09:43:17 GMT Server: Apache/2.2.3 (CentOS) Content-Length: 0 Connection: close Content-Type: text/html;charset=utf-8
Read service
We have covered the documentation for the RESTful Query web services in the RIPE Labs document located here:
http://labs.ripe.net/ripe-database/database-api/api-documentation
Create service
In this example we will create a new PERSON object. We will use the MNTNER object that we created earlier using the Start-up service.
The XML:
<?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>
The <attribute name="nic-hdl" value="AUTO-1" /> element tells the RIPE Database to auto generate a NIC Handle value for this new PERSON object.
The full 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://lab.db.ripe.net/whois/create?password=123 -D headers.txt
headers.txt stores the response header in a textfile called headers.txt
> more headers.txt
shows:
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://lab.db.ripe.net/whois/lookup/test/person/PP16-TEST Content-Length: 0 Connection: close Content-Type: text/plain; charset=UTF-8
Success! We have created a new PERSON object with the NIC Handle "PP16-TEST". You should keep a note of this NIC Handle for future reference.
Update service
This service replaces a full object with the new one described in the request body XML.
The XML:
<?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>
The full CURL command:
> curl -X PUT -H 'Content-Type: application/xml' -d '<?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="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://lab.db.ripe.net/whois/update/test/person/pp16-test?password=123 -D headers.txt
Response body:
<?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://lab.db.ripe.net/whois/lookup/test/person/PP3-TEST"/> <objects> <object type="person"> <link xlink:type="locator" xlink:href="http://lab.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://lab.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>
> more headers.txt
shows:
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
Delete service
It is possible to delete a RIPE Database object over REST using the DELETE verb. Instead of having to provide the full RIPE RPSL object with the Delete service, you will just have to provide the object type, the primary key of the object, one or more maintainer passwords and optionally the reason for the deletion.
The full CURL command:
> curl -X DELETE https://lab.db.ripe.net/whois/delete/test/person/pp16-test?password=123 -D headers.txt
It is possible to provide a reason for deletion by adding &reason=text after the password parameter.
> more headers.txt
shows:
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 use case based object manipulation services
These services perform some powerful actions. They relieve our clients from the burden of implementing the complex parsing and processing required to change, replace, add and do other operations on object attributes.
The specific end point URI for this service is:
https://lab.db.ripe.net/whois/modify/<source>/<object-type>/<primary-key>
This service is exposed with the POST verb and is operated submitting an XML that will describe the action you want to execute on a given object and the changes to be applied.
This XML has a different schema than the one we use to describe objects since it is focused on processing an object, not just representing it.
The three actions on attributes that we have implemented until now are:
- Replace
- Add
- Remove
Note that none of these actions will allow you to change the primary key or the first attribute (where it is not the primary key) of an object.
The best way to explain how it works exactly is by using some examples...
Replace attributes
This action may be very handy in the case of an address change for example. Just submit the new address attributes for a given object and they will replace all the current address attributes.
<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>
As you can see in the last XML "attribute" element the action also allows for flexibility on what is going to replace the old attributes. The new attributes don't have to be of the same type as the overwritten type and don't even have to be all of the same type. But for the replace to succeed the final object will still need to contain all the mandatory attributes required for the given object type, otherwise you will get an error response.
Here's the full CURL request:
> 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://lab.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt
Response body:
<?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://lab.db.ripe.net/whois/lookup/test/person/PP16-TEST"/> <objects> <object type="person"> <link xlink:type="locator" xlink:href="http://lab.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://lab.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>
> more headers.txt
shows:
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
Appending attributes to an existing object can be achieved using the add action as follows:
<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>
Here's the full CURL request:
> 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://lab.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt
Response body:
<?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://pre.db.ripe.net/whois/lookup/test/person/PP16-TEST"/> <objects> <object type="person"> <link xlink:type="locator" xlink:href="http://pre.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://pre.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>
> more headers.txt
shows:
HTTP/1.1 200 OK Date: Wed, 29 Dec 2010 10:52:37 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
And the above attributes have just been appended to the object.
Add new attributes starting from the Nth line
<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>
Please note that we start counting lines at index=0 for the first attribute of the object.
In case the index that you specify is out of bounds (the Nth attribute doesn't exist), the attributes will be appended to the end of the object.
It is also important to note that the attributes that were originally positioned at indices starting from the given one will be shifted down of the number of a number of lines equals to the number of new attributes being added.
|
Changing primary attribute Please note that changing the primary value of an object (the value of attribute at index 0) is not permitted. Any attempt of adding attributes at line 0 will result in a failure response. |
|---|
Here's the full CURL request:
> 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://lab.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt
Response body:
<?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://lab.db.ripe.net/whois/lookup/test/person/PP16-TEST"/> <objects> <object type="person"> <link xlink:type="locator" xlink:href="http://lab.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="below the 6th attribute (at 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://lab.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>
> more headers.txt
shows:
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
<whois-modify> <remove attribute-type="remarks"/> </whois-modify>
Here's the full CURL request:
> curl -X POST -H 'Content-Type: application/xml' -d '<whois-modify> <remove attribute-type="remarks"/></whois-modify>' https://lab.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt
Response body:
<?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://lab.db.ripe.net/whois/lookup/test/person/PP16-TEST"/> <objects> <object type="person"> <link xlink:type="locator" xlink:href="http://lab.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://lab.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>
> more headers.txt
shows:
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
Note that this operation may cause the index of attributes to change, because attributes of the type that is being removed may be at different points in your object. Also note that an attempt to remove mandatory attributes will result in a failure response.
Remove the Nth attribute
<whois-modify> <remove index="6"/> </whois-modify>
|
Removing primary attribute The primary attribute of an object cannot be changed, any attempt to remove line 0 attribute will result in a failure response |
|---|
Here's the full CURL request:
> curl -X POST -H 'Content-Type: application/xml' -d '<whois-modify> <remove index="6"/></whois-modify>' https://lab.db.ripe.net/whois/modify/test/person/pp16-test?password=123 -D headers.txt
Response body:
<?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://lab.db.ripe.net/whois/lookup/test/person/PP16-TEST"/> <objects> <object type="person"> <link xlink:type="locator" xlink:href="http://lab.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://lab.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>
> more headers.txt
shows:
HTTP/1.1 200 OK Date: Wed, 29 Dec 2010 11:08:21 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
Please note that the removal of an attribute will shift all the subsequent attributes up by one index. Also note that in case the resulting object doesn't contain all the mandatory attributes for its type anymore, your request will result in a failure response.
Feedback
As usual, we are very much interested in your feedback. We would also like to know if you are running a project in which you used the RIPE Database API.
Comments 0
Comments are disabled on articles published more than a year ago. If you'd like to inform us of any issues, please reach out to us via the contact form here.