Archive 1.x:Endpoints Access (OSF Web Service)

From OSF Wiki
Jump to navigation Jump to search

The way to communicate with any OSF Web Service is by using the HTTP protocol. Any Web service endpoint can be accessed via its URL, which may combine an overall service name (e.g., 'crud') with its specific implementation or focus (e.g., 'read'). A URL example is:

The standard text reference to this example Web service then becomes:

Crud: Read Web Service

Communication Methods

There are two methods that can be used to communicate with a Web service endpoint: GET or POST. The method to use differs from one service to another. This method is specified in the API documentation of each Web service.

Below is a description of the HTTP header that a data consumer should use to request a resultset to Web services that returns resultsets information. For example, the Crud: Read Web service will return a list of properties describing an instance record in a resultset. However, Crud: Create will only return a HTTP status (200) to say that the instance record has been successfully created, and return another status if there has been an error. In any case, Crud: Create wont return any resultset.

GET Method

HTTP header sent by the data consumer:

GET /ws/crud/read/?uri=http://yoursite.org/drupal/conStruct/datasets/260/resource/test2&dataset=http://yoursite.org/wsf/datasets/260/&include_linksback=true HTTP/1.1

User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 Host: yoursite.org

Accept: application/rdf+xml

The HTTP header sent by back by the Web service endpoint:

HTTP/1.1 200 OK

Date: Wed, 20 May 2009 15:33:16 GMT Server: Apache/2.2.8 (Ubuntu) PHP/5.2.4-2ubuntu5.4 with Suhosin-Patch X-Powered-By: PHP/5.2.4-2ubuntu5.4 Content-Language: en Content-Encoding: identity Content-Type: application/rdf+xml; charset=utf-8 Content-Language: en Content-Encoding: identity

Content-Length: 236

Additionally the data consumer can specify different charsets, language and encoding in its request. However only the "utf-8" charset, the "en" language and the "identity" encoding are supported by the baseline OSF Web Services endpoints.

POST Method

HTTP header sent by the data consumer:

POST /ws/crud/create/ HTTP/1.1

User-Agent: curl/7.16.3 (powerpc-apple-darwin9.0) libcurl/7.16.3 OpenSSL/0.9.7l zlib/1.2.3 Host: yoursite.org Accept: text/xml Content-Length: 223

Content-Type: application/x-www-form-urlencoded

The HTTP header sent by back by the Web service endpoint:

HTTP/1.1 200 OK

Date: Wed, 20 May 2009 16:00:39 GMT Server: Apache/2.2.8 (Ubuntu) PHP/5.2.4-2ubuntu5.4 with Suhosin-Patch X-Powered-By: PHP/5.2.4-2ubuntu5.4 Content-Language: en Content-Encoding: identity Content-Length: 0

Content-Type: text/xml; charset=utf-8

Additionally the data consumer can specify different charsets, language and encoding in its request. However only the "utf-8" charset, the "en" language and the "identity" encoding are supported by the baseline OSF Web Services endpoints.

Note that the parameters to pass to the Web service endpoint are added in the body of the query.

For a complete description of HTTP/1.1 header fields, please consult the RFC 2616 document.

Examples of Web Service Endpoint Queries

In this section we will explain how to get access to a OSF Web Service via a CMS and how to query the endpoints externally using Curl.

Register an External IP to OSF Web Service

  1. Go to that address which is a CMS (Drupal) wrapper over a OSF Web Service: http://yoursite.org/drupal/
  2. Login with your existing user name, or create a new one here.
  3. Now that you are logged-in, you have to register the IP address of the computer that will send the Curl queries to the endpoints. Click here to put your IP address and to save it to the system.
  4. Send your IP address to the OSF Web Service administrator so that he can give you FULL access to the OSF Web Service. Otherwise, you wont be able to create and manage datasets, but only instance records.

Once you have performed these four steps, you are ready to send some queries to the endpoints.

Send Queries to the Endpoints

Note: When you Copy & Paste these examples from your web browser, make sure that you remove ALL spaces that can be introduced by this Copy & Paster operation. The Curl query should be on one single line without any space (except between the Curl parameters) and any return carrier.

Step 1: Create a new Dataset

Step 2: Create an Access to this Dataset

Query: curl -H "Accept: text/xml" "http://yoursite.org/ws/auth/registrar/access/" -d "registered_ip=24.200.138.116&crud=true;true;true;true&ws_uris=http://yoursite.org/wsf/ws/crud/read/;http://yoursite.org/wsf/ws/crud/create/;http://yoursite.org/wsf/ws/crud/delete/&dataset=http://dataset.com/test/&action=create" -v
Parameters: registered_ip: 24.200.138.116
crud: true;true;true;true
ws_uris: http://&/ws/crud/read/;http://&/ws/crud/create/;http://&/ws/crud/delete/
dataset: http://dataset.com/test/
action: create

Step 3: Create a Instance Record

Query: curl -H "Accept: text/xml" "http://yoursite.org/ws/crud/create/" -d "document=%3Chttp%3A%2F%2Fyoursite.org%2Fdrupal%2Fbkn%2Fdatasets%2F144%2Fresource%2Ftest3%3E+a+%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2FPerson%3E.&dataset=http://dataset.com/test/&mime=application%2Frdf%2Bn3" -v
Parameters: Document: RDF/N3 document to index
Dataset: http://dataset.com/test/
Mime: application/rdf+n3

Step 4: Read an Instance Record

Step 5: Delete an Instance Record

In this example we demonstrated how to query the OSF Web Service using Curl. The user has to keep in mind that this can be done using any programming language since most (if not all) of them have such querying capabilities within their APIs. One example of this is how the Drupal module is communicating with the OSF Web Service by using its own Curl API.