4. Web API
Representations of dereferenced resources in Pinetree are determined according to 1) the preference of the client or 2) the call itself. The template to which all resources in the system adhere to is the following:
{root_url}/{mode}/[..]
Here, the {root_url} specifies the root URL of the Pinetree application instance, while the representation of a specific resource is determined by {mode}. All resources in Pinetree have {mode} set to “resource” in their URI. E.g., the URI of the main collection is:
{root_url}/resource/collection/main
By default, the Pinetree application automatically generates a collection with {id} set to “main” on its first startup, to which all created resources belong. When the URI above is dereferenced, the preference of the client decides whether the call should return a human-readable representation of the data in HTML or as machine-processable RDF according to the Linked Data best practices (http://www4.wiwiss.fu-berlin.de/bizer/pub/LinkedDataTutorial/). By changing the value of {mode} to either “page” or “data”, the preferences of the client is overridden.
The Web API as defined in the vanilla routing configuration (see linkeddata-servlet.xml in the vanilla release) is described in the respective sections below.
4.1 Collection
Web API pattern: {root_uri}/{mode}/collection/{id}
Method: GET
| Description | Dereferences the collection resource, returning either an HTML or RDF representation based on 1) the preference of the client or 2) the call itself. |
| Parameters | media Optional. When {mode} is set to “data”, the query parameter media can be used to specify the RDF format to be delivered to client. Possible values are “rdfxml”, “n3″, “ttl” and “trix” for RDF/XML, n3, Turtle and TRiX formats respectively. If the parameter is omitted, RDF/XML is returned. |
| Returns | HTML or RDF |
Method: PUT
| Description | Add, remove or update metadata of the collection resource. |
| Parameters | add Optional. Adds the statements present in the parameter. Must be a JSON array formatted according to the structure below. The subject-predicate-object represents a statement in which the URI of the current resource must match the contents of thevalue variable in either the subject or object. type is a mandatory variable with the possible values “literal” or “URI”. The datatype variable is optional and can be used only if type is specified as “literal” in order to set the datatype of the literal. The value of datatype must be formatted as a URI, e.g. http://www.w3.org/2001/XMLSchema#int. [{ remove [{ |
| Returns | HTTP response code 200 on success.HTTP response code 400 if the parameters were malformed. HTTP response code 500 on internal server error. |
4.2 Part
Web API pattern: {root_uri}/{mode}/part/{id}
All parts stored in Pinetree are identified according to the address above, where {id} specifies the local name of the part.
Method: GET
| Description | Dereferences the part resource, returning either an HTML or RDF representation based on 1) the preference of the client or 2) the call itself. |
| Parameters | media Optional. When {mode} is set to “data”, the query parameter media can be used to specify the RDF format to be delivered to client. Possible values are “rdfxml”, “n3″, “ttl” and “trix” for RDF/XML, n3, Turtle and TRiX formats respectively. If the parameter is omitted, RDF/XML is returned. |
| Returns | HTML or RDF |
Method: POST
| Description | Attempts to create a part resource. The local name of the part is determined by the value of {id}. |
| Parameters | - |
| Returns | HTTP response code 200 on success and redirects to the newly created content. HTTP response code 400 if the parameters were malformed. HTTP response code 500 on internal server error. |
Method: PUT
| Description | Add, remove or update metadata of a part resource. |
| Parameters | add Optional. Adds the statements present in the parameter. Must be a JSON array formatted according to the structure below. The subject-predicate-object represents a statement in which the URI of the current resource must match the contents of thevalue variable in either the subject or object. type is a mandatory variable with the possible values “literal” or “URI”. Thedatatype variable is optional and can be used only if type is specified as “literal” in order to set the datatype of the literal. The value of datatype must be formatted as a URI, e.g. http://www.w3.org/2001/XMLSchema#int. [{ remove [{ |
| Returns | HTTP response code 200 on success. HTTP response code 400 if the parameters were malformed. HTTP response code 500 on internal server error. |
Method: DELETE
| Description | Attempts to remove the part. |
| Returns | HTTP response code 200 on success. HTTP response code 500 on internal server error. |
4.3 Content
Web API pattern: {root_uri}/{mode}/content/{id}
All content created in Pinetree are identified according to the address above, where {id} specifies the local name of the content.
Method: GET
| Description | Dereferences the content resource, returning either an HTML or RDF representation based on 1) the preference of the client or 2) the call itself. |
| Parameters | media Optional. When {mode} is set to “data”, the query parameter media can be used to specify the RDF format to be delivered to client. Possible values are “rdfxml”, “n3″, “ttl” and “trix” for RDF/XML, n3, Turtle and TRiX formats respectively. If the parameter is omitted, RDF/XML is returned. |
| Returns | HTML or RDF |
Method: POST
| Description | Attempts to create the resource. The local name of the content is determined by the value of {id}. |
| Parameters | content Mandatory. Can either be a string containing a URL to a remote resource or a file as a multipart request. |
| Returns | HTTP response code 200 on success and redirects to the newly created content. HTTP response code 400 if the parameters were malformed. HTTP response code 500 on internal server error. |
Method: PUT
| Description | Add, remove or update metadata of a content resource. |
| Parameters | add Optional. Adds the statements present in the parameter. Must be a JSON array formatted according to the structure below. The subject-predicate-object represents a statement in which the URI of the current resource must match the contents of thevalue variable in either the subject or object. type is a mandatory variable with the possible values “literal” or “URI”. Thedatatype variable is optional and can be used only if type is specified as “literal” in order to set the datatype of the literal. The value of datatype must be formatted as a URI, e.g. http://www.w3.org/2001/XMLSchema#int. [{ remove [{ |
| Returns | HTTP response code 200 on success. HTTP response code 400 if the parameters were malformed. HTTP response code 500 on internal server error. |
Method: DELETE
| Description | Attempts to remove the content. |
| Returns | HTTP response code 200 on success. HTTP response code 500 on internal server error. |