Server

Fast, realiable, open.

General info

The Pundit server is a Java application implementing a REST API using the Jersey framework (http://jersey.java.net).

Annotations are represented in RDF as stored into a triple-store, that provides standard SPARQL endpoint for querying data. The server has been designed to conform to Open Annotation specifications, however, as such specifications have been under development and only recently reached a stable state (http://www.openannotation.org/spec/core/) we are still working to implement full compliancy. That is why we do not have a data model documentation yet...it is coming soon.

The current demo instance of the server is available at Semedia server (http://metasound.dibet.univpm.it/annotationserver/) uses the Sesame open-source triplestore (http://www.openrdf.org/). Users permissions and other metadata are stored in a relational database for fast access.

In this page we provide API documentation and we are soon going to add more specific resources for developers (e.g. javadoc, installation instructions) soon.

Open ID

In order to use the API, the user needs to authenticate using the OpenID workflow: the Pundit server will start the communication with your OpenID provider (google, yahoo!, AOL .. you name it!) redirecting the user to a login page hosted on the provider’s servers. At this point the user can provide username and password and get authenticated by the chosen OpenID provider. If the login process is successful, a server-to-server communication happens: the Pundit server now keeps track of the logged in user just by its OpenID identifier. Read more about OpenID on http://openid.net/.

The main benefits of this approach are:

  • Our Pundit server does not need to store user’s credentials, avoiding all of the complications this could bring up
  • The chances that an average internet user owns an OpenID are humongous: a lot of very big internet companies implements this workflow already: google, yahoo, facebook..
  • Using an existing account avoids the pain of remembering a billion of username/password pairs
  • Using an existing account permits a single identity to be used among different Pundit-enabled Digital Libraries, creating connections with no extra effort
  • Adding an OpenID provider is easy and transparent to the Pundit server. If you already have a user base, just implement the OpenID provider scheme, and you’re good to go!
  • Creating a new account is trivial: just choose one of the provider Pundit already supports

Support for Cross-domain Requests

The Annotation Server support cross-domain requests using CORS and JSONP. CORS is completely transparent to the client and can be used in recent Web browsers for HTTP requests with methods: HEAD, GET, PUT, POST, DELETE and OPTIONS. Following, the list of Web browsers that support CORS natively:

  • Internet Explorer 8+ (partial support via the XDomainRequest object)
  • Mozilla Firefox 3.5+
  • Apple Safari 4+
  • Google Chrome 3+

Differently to CORS, JSONP can be also used in old Web browsers but only for HTTP GET requests. To use JSONP for GET requests, a callback function must be specified adding the parameter “jsonp=” as shown in the following example.

   GET /annotationserver/api/notebooks/current?jsonp=processData

Consuming API

This set of API allow users to get all data and metadata about Notebooks and Annotations in different formats like: plain text (that can also be rendered in HTML pages using stylesheets), JSON, RDF+XML and RDF+N3.

Base URL: http://{WEBSERVER ADDRESS}/annotationserver/api

GET /notebooks/current

Returns the ID of the Notebook where the active user writes annotations by default (current notebook).

Output Data Formats
  • application/json
Output Payload Formats
  • { "NotebookID": "ID" }
Note

For the prototype version of the Annotation Server, all users write on the same notebook.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there is no active Notebook
  • 400 Bad Request, if the request is not correct
  • 500 Internal Server Error, if some internal server errors have occurred

GET /notebooks/public/{Notebook-ID}

Check if a specified Notebook is public or not.

Output Data Formats
  • application/json
Output Payload Formats
  • { "NotebookPublic": "1|0" }: 1: the specified Notebooks is Public; 0: the specified Notebook is Private
Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

GET /notebooks/owned

Return the list of all Notebooks owned by the current logged user.

Output Data Formats
  • application/json
Output Payload Formats
  • { "NotebookIDs": ["11111111", "22222222"] }
Returned Status Code
  • "200 OK", in case of success
  • "204 No Content", if the current logged user does not own any Notebooks
  • "400 Bad Request", if the request is not correct
  • "403 Forbidden", if no users is logged or if the current logged user has not the correct rights to access to this API
  • "500 Internal Server Error", for internal server error

GET /notebooks/active/{Notebook-ID}

Check if a specified Notebook is active or not.

Output Data Formats
  • application/json
Output Payload Formats
  • { "NotebookActive": "1|0" }: 1: the specified Notebooks is set as "active"; 0: the specified Notebook is set as "not active"
Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

GET /notebooks/active

Return the list of all active Notebooks for the current logged user.

Output Data Formats
  • application/json
Output Payload Formats
  • { "NotebookIDs": ["11111111", "22222222"] }
Returned Status Code
  • "200 OK", in case of success
  • "204 No Content", if there are no active Notebooks for the current logged user
  • "400 Bad Request", if the request is not correct
  • "403 Forbidden", if no users is logged or if the current logged user has not the correct rights to access to this API
  • "500 Internal Server Error", for internal server error

GET /notebooks/{Notebook-ID}/metadata

Get all metadata about a specified Notebooks.

Parameters
  • Notebook-ID, a valid notebook ID
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no metadata about the specified Notebooks
  • 400 Bad Request, if the notebook ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged user has not the correct right to access the specified Notebook
  • 404 Not Found, if the specified notebook does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

GET /notebooks/{Notebook-ID}?limit=limit&offset=offset&orderby=orderby&orderingMode=1|0

Get the list of all annotation contained within a Notebook with related metadata.

Parameters
  • Notebook-ID, a valid notebook ID
  • limit, (optional) specify the maximum number of annotations to retrieve. Default: -1 (all annotations)
  • offset, (optional) specify the starting point from which the annotations will be retrieved. Default: -1 (start from the first annotation)
  • orderby, (optional) specify the RDF property used to order the annotations. Default: dc:created
  • desc, (optional) specify if the results should be sorted using a descending order (desc=1) or an ascending order (desc=0). Default: 0
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no annotations or triples in the specified notebooks
  • 400 Bad Request, if the notebook ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged user has not the correct right to access the specified Notebook
  • 404 Not Found, if the specified notebook does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

GET /notebooks/current/graph

For each annotation contained in the current Notebook for the current logged User, return all triples without Annotation’s metadata.

Parameters
  • Notebook-ID, a valid notebook ID
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no annotations or triples in the specified notebooks
  • 400 Bad Request, if the notebook ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged user has not the correct right to access the specified Notebook
  • 404 Not Found, if the specified notebook does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

GET /notebooks/{Notebook-ID}/graph

For each annotation contained in the specified Notebook, return all triples without Annotation’s metadata.

Parameters
  • Notebook-ID, a valid notebook ID
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no annotations or triples in the specified notebooks
  • 400 Bad Request, if the notebook ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged user has not the correct right to access the specified Notebook
  • 404 Not Found, if the specified notebook does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

GET /annotations/{Annotation-ID}/metadata

Return all metadata about the specified Annotation.

Parameters
  • Annotation-ID, a valid Annotation ID
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no annotations with the specified Annotation-ID
  • 400 Bad Request, if the Annotation-ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to access to the Notebook that contains the specified Annotation
  • 500 Internal Server Error, if some internal server errors have occurred

GET /annotations/{Annotation-ID}/content

Returns all data triples (without metadata) about the specified Annotation.

Parameters
  • Annotation-ID, a valid Annotation ID
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no annotations with the specified Annotation-ID
  • 400 Bad Request, if the Annotation-ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to access to the Notebook that contains the specified Annotation
  • 500 Internal Server Error, if some internal server errors have occurred

GET /annotations/{Annotation-ID}/items

Return all Items associated to a given annotation.

Parameters
  • Annotation-ID, a valid Annotation ID
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no annotations with the specified Annotation-ID
  • 400 Bad Request, if the Annotation-ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to access to the Notebook that contains the specified Annotation
  • 500 Internal Server Error, if some internal server errors have occurred

Authoring API

This set of API allow user to create new notebooks and annotations as well as edit or delete existing ones and modify their metadata.

Base URL: http://{WEBSERVER ADDRESS}/annotationserver/api

PUT /notebooks/{Notebook-ID}/public

Set the specified Notebook as Public.

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

PUT /notebooks/private/{Notebook-ID}

Set the specified Notebook as Private.

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

DELETE /notebooks/private/{Notebook-ID}

Set the specified Notebook as Public. This API is an alias of the API `PUT /notebooks/{Notebook-ID}/public

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

DELETE /notebooks/public/{Notebook-ID}

Set the specified Notebook as Private. This API is an alias of the API `PUT /notebooks/{Notebook-ID}/private

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

PUT /notebooks/current/{Notebook-ID}

Set the specified Notebooks as "current". If another Notebook is already set as "current", this API set it as "not current".

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

PUT /notebooks/active/{Notebook-ID}

Activate a specified Notebook

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request or the specified Notebooks ID is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

DELETE /notebooks/active/{Notebook-ID}

Deactivate a specified Notebook. By default a Notebook set as current can not be deactivated. If a user try to deactivate a Notebook that is set as current, this API return a 403 HTTP error.

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request or the specified Notebooks ID is not correct
  • 403 Forbidden, if the current logged user has not the correct rights to access to the specified Notebook
  • 404 Not Found, if the specified Notbook does not exist
  • 500 Internal Server Error, if some internal server errors have occurred

POST /notebooks/

Creates a new Notebook. This API return the ID of the created Notebook in response’s payload in JSON format and the full URL of the Notebook adding a Location header into the HTTP response. The name of the new Notebook can be specified sending a specific payload.

Request Payload
  • Payload must be encoded in JSON format and it is optional. If the Notebook’s name is not specified, the Annotation Server will create a new Notebook with a default name (e.g. Notebook 27-09-2011). Payload format: { ”NotebookName”: ”My new Notebook” }
Request Headers
  • Content-Type, required if the request includes the payload to specify the notebook’s name. Possible values: application/json
Otuput Data Formats
  • Data format: application/json, the ID of the new Notebooks. Response example: { ”NotebookID”: ”4C82F27D” }
Returned Status Code
  • 201 Created, in case of success
  • 400 Bad Request, if the request is not correct or if the request’s payload is not valid
  • 500 Internal Server Error, if some internal server errors have occurred

POST /notebooks/{Notebook-ID}?context={JSON-DATA}

Creates a new Annotation with a unique ID in the specified Notebooks. The Annotation’s triples must be sent in the request’s payload. The ID of the new Annotation is returned to the client in the response’s payload. This API also returns the full URL of the created Annotation adding a Location header into the HTTP response.

Parameters
  • Notebook-ID, a valid Notebook ID
  • JSON-DATA (optional), additional annotation metadata in JSON format. The JSON data must be URL encoded. Example of JSON-DATA: { ”targets”: [ ”URL1”, ”URL2”, ..], ”pageContext”: ”URL3” }
Request Payload
  • Request’s payload must contains the Annotation’s triples encoded using one of the supported data formats, which must be specified by the Content-Type header of the HTTP request.
Request Headers and Input Data Formats
  • Content-Type, specify the encoding of the input payload. Possible values: application/json, application/rdf+xml, text/rdf+n3
Output Format and Data
  • Data format: application/json, the ID of the new Annotation. Response example: { ”AnnotationID”: ”AF82E22D”}
Returned Status Code
  • 201 Created, in case of success
  • 400 Bad Request, if the request is not correct or if the request’s payload is not valid
  • 403 Forbidden, if the current logged user has not the correct right to create a new Annotation into the specified Notebook
  • 500 Internal Server Error, if some internal server errors have occurred

POST /notebooks/current

Create a new Annotation e put it into the default Notebooks of the current active user. The Annotation’s triples must be sent in the request’s payload. The ID of the new Annotation is returned to the client in the response’s payload. This API also returns the full URL of the created Annotation adding a Location header into the HTTP response.

Request Payload

Request’s payload must contains the Annotation’s triples encoded using one of the supported data formats, which must be specified by the Content-Type header of the HTTP request.

Request Headers and Input Data Formats
  • Content-Type, specify the encoding of the input payload. Possible values: application/json, application/rdf+xml, text/rdf+n3
Output Format and Data
  • Data format: application/json, the ID of the new Annotation. Response example: { ”AnnotationID”: ”AF82E22D”}
Returned Status Code
  • 201 Created, in case of success
  • 400 Bad Request, if the request is not correct or if the request’s payload is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to create a new Annotation into the current Notebook
  • 500 Internal Server Error, if some internal server errors have occurred

POST /annotations/{Annotation-ID}

Add new triples to an already existing Annotations. This API does not duplicate already existing triples. The new triples must be sent in the request’s payload and must be encoded in one of the supported data formats.

Parameters
  • Annotation-ID, the ID of an existing Annotation
Request Payload
  • Request’s payload must contains the Annotation’s triples encoded using one of the supported data formats, which must be specified by the Content-Type header of the HTTP request
Request Headers and Input Data Formats
  • Content-Type, specify the encoding of the input payload. Possible values: application/json, application/rdf+xml, text/rdf+n3
Returned Status Code
  • 200 Ok, in case of success
  • 400 Bad Request, if the request is not correct, if the request’s payload or if the Annotation ID is not valid
  • 403 Forbidden, if the current logged User has not the correct right to edit the specified Annotation
  • 404 Not Found, if the specified Annotation does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

PUT /notebooks/{Notebook-ID}

Modify the metadata of an existing Notebook. In the current version, this API can be used only to change the Notebook’s name. The new Notebook’s name must be sent as request’s payload and must be encoded in JSON format.

Parameters
  • Notebook-ID, the ID of an existing Notebook
Request Payload
  • Payload must be encoded in JSON format. Payload format: { ”NotebookName”: ”My new Notebook” }
Request Headers
  • Content-Type, specify the payload data type. Possible values: application/json
Returned Status Code
  • 200 Ok, in case of success
  • 400 Bad Request, if the request is not correct, if the request’s payload or if the Notebook ID is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to edit the specified Notebook
  • 404 Not Found, if the specified Annotation does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

PUT /annotations/{Annotation-ID}/content

Overwrites the triples of an existing Annotation and modifies the related metadata (e.g. modified date). The new triples must be sent in the request’s payload and must be encoded in one of the supported data formats.

Parameters
  • Annotation-ID, the ID of an existing Annotation
Request Payload
  • Request’s payload must contains the Annotation’s triples encoded using one of the supported data formats, which must be specified by the Content-Type header of the HTTP request
Request Headers
  • Content-Type, specify the payload data type. Possible values: application/json, application/rdf+xml, text/rdf+n3
Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct, if the request’s payload or if the Annotation ID is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to edit the specified Annotation
  • 404 Not Found, if the specified Annotation does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

POST /annotations/{Annotation-ID}/items

Add new Items to an existig annotation specified by the annotation ID.

Parameters
  • Annotation-ID, the ID of an existing Annotation
Request Payload
  • Request’s payload must contains the Annotation’s Items encoded using one of the supported data formats, which must be specified by the Content-Type header of the HTTP request
Request Headers
  • Content-Type, specify the payload data type. Possible values: application/json, application/rdf+xml, text/rdf+n3
Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct, if the request’s payload or if the Annotation ID is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to edit the specified Annotation
  • 404 Not Found, if the specified Annotation does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

PUT /annotations/{Annotation-ID}/items

Overwrite triples of an existig annotation specified by the annotation ID.

Parameters
  • Annotation-ID, the ID of an existing Annotation
Request Payload
  • Request’s payload must contains the Annotation’s Items encoded using one of the supported data formats, which must be specified by the Content-Type header of the HTTP request
Request Headers
  • Content-Type, specify the payload data type. Possible values: application/json, application/rdf+xml, text/rdf+n3
Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the request is not correct, if the request’s payload or if the Annotation ID is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to edit the specified Annotation
  • 404 Not Found, if the specified Annotation does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

DELETE /notebooks/{Notebook-ID}

Delete the Notebook with the specified ID. If the notebook contains some Annotations, this API also deletes all Annotations contained within it.

Parameters
  • Notebook-ID, the ID of an existing Notebook
Returned Status Code
  • 204 No Content, in case of success
  • 400 Bad Request, if the request is not correct or if the Notebook ID is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to delete the specified Notebooks
  • 404 Not Found, if the specified Notebook does not exists
  • 500 Internal Server Error, if some internal server errors have occurred

DELETE /annotations/{Annotation-ID}

Delete the Annotation with the specified ID.

Parameters
  • Annotation-ID, the ID of an existing Annotation
Returned Status Code
  • 204 No Content, in case of success
  • 400 Bad Request, if the request is not correct or if the Annotation ID is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to edit the specified Annotation
  • 404 Not Found, if the specified Annotation does not exists
  • 500 Internal Server Error, if some internal server error will occur

Searching API

This set of API allow users to search for Notebooks and Annotations basing on specific searching parameters. The prototype version of the Annotation Server provides only a single searching API with simple searching parameters.

Base URL: http://{WEBSERVER ADDRESS}/annotationserver/api

GET /notebooks/{Notebook-ID}/search?query=query

Searches for all Annotation’s metadata in a specified Notebook according to the specified parameters. In the current version, the only supported searching parameter is resources. Specifying one or more resources, this API return all metadata of Annotations that have one of the specified resource as hasTarget and hasPageContext. In addition, this API returns all metadata of Annotations that have as hasTarget a resource that isPartOf of one of the specified resources.

Parameters
  • query, specify the searching parameters. These parameters must be in JSON format.
Request Headers and Output Data Formats
  • Accept* (mandatory), specify the encoding format of the output payload. Possible values: application/json, application/rdf+xml, text/rdf+n3
Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no metadata according to the specified searching parameters
  • 400 Bad Request, if the request is not correct or if the searching parameters are not correct
  • 403 Forbidden, if the current logged User has not the correct rights to read the specified Notebooks
  • 500 Internal Server Error, if some internal server errors have occurred

GET /annotations/metadata/search?query=query

Searches for all Annotation’s metadata according to the specified parameters. In the current version, the only supported searching parameter is resources. Specifying one or more resources, this API return all metadata of Annotations that have one of the specified resource as hasTarget and hasPageContext. In addition, this API returns all metadata of Annotations that have as hasTarget a resource that isPartOf of one of the specified resources.

Parameters
  • query, specify the searching parameters. These parameters must be in JSON format. Example of searching parameters: { ”resources”: [”URL1”, ”URL2”, ...] }
  • scope, possible values: all (default), search in all public Notebooks; active, search in all Notebook set as "active" by the current logged user
Request Headers and Output Data Formats
  • Accept* (mandatory), specify the encoding format of the output payload. Possible values: application/json, application/rdf+xml, text/rdf+n3
Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no metadata according to the specified searching parameters
  • 400 Bad Request, if the request is not correct or if the searching parameters are not correct
  • 500 Internal Server Error, if some internal server errors have occurred

GET /annotations/{Annotation-ID}/items/search

Search for all annotation's Items basing on specific searching parameters.

Parameters
  • Annotation-ID, a valid Annotation ID
  • query, specify the searching parameters. These parameters must be in JSON format.
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if there are no annotations with the specified Annotation-ID
  • 400 Bad Request, if the Annotation-ID is not specified or if it is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to access to the Notebook that contains the specified Annotation
  • 500 Internal Server Error, if some internal server errors have occurred

Users API

This set of API can be used to obtain all information about a registered user of the AnnotationServer or to perform specific operations regarding users management.

Base URL: http://{WEBSERVER ADDRESS}/annotationserver/api/

GET /users/current

Return all information about the current logged user in JSON format. The API can return different results basing on the login status of the current user (see Output Data Model section for more information).

Output Data Formats
  • application/json
Output Data Model
  1. For logged users

    { “loginStatus”: 1,
      "id": "USER_ID",
      "uri": "USER_ID_URI",
      "openID": "USER_OPENID", 
      “firstName”: “FIRST_NAME”,
      “lastName”: “LAST_NAME”,
      “fullName”: “FULLNAME”,
      "email": "EMAIL_ADDRESS" }
  2. Not logged user

    { “loginStatus”: 0,
      “loginServer”:  “URL_TO_LOGIN_SERVER”}

About the returned JSON for logged users: USER_ID is a value that is independent from the user's openID (example: 3C9AFF08); USER_ID_URI is the URI generated starting from the USER_ID (example: http://swickynotes.org/notebook/resource/3c9aff08); USER_OPRNID is the user's OpenID URI. Other fields such as firstName, lastName, fullName, email are optional.

Returned Status Code
  • 200 Ok, in case of success
  • 500 Internal Server Error*, if some internal server errors have occurred

GET /users/logout

Logout the current logged user and return the results of the logout operation as JSON data (see Output Data Model for more information).

Output Data Formats
  • application/json
Output Data Model
  1. If this API is called when the user is not logged yet, it returns this JSON data: { “logout”: 0 }
  2. if this API is called when the user is logged and the logout process is correctly performed, it returns this JSON data: { “logout”: 1 }
Returned Status Code
  • 200 Ok, in case of success
  • 500 Internal Server Error*, if some internal server errors have occurred

GET /users/{USER-ID}

Return all information about a specified user in different data formats.

Parameters
  • user-id, a valid user ID
Output Data Formats
  • application/json
  • application/rdf+xml
  • text/rdf+n3

The output data format must be specified setting the Accept HTTP header.

Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the user ID is not specified or if it is not valid
  • 404 Not Found, if the specified user does not exist
  • 500 Internal Server Error*, if some internal server errors have occurred

Services API

This set of API contains the implementation of useful services for the AnnotationServer.

Base URL: http://{WEBSERVER ADDRESS}/annotationserver/api/services/

GET /proxy?url=ENCODED_URL

This API implement an HTTP transparent proxy. In can be used to download any textual contents or files that is hosted in third party servers in order to overcome the limits imposed by the same-origin-policy. This API return the same Content-Type and the same HTTP response code returned by the original request (same Content-Type and same HTTP response code returned if the user request the ENCODED_URL without using the proxy). If the server the hosted the resource identified by the ENCODED_URL supports different output data formats, it is possible to specify the preferred data format specifying the Accept header before sending the request to the proxy.

Parameters
  • ENCODED_URL, the encoded absolute URL of the resource to download
Returned Status Code
  • 400 Bad Request, if the request is not correct or if the requested resource is hosted in a server that does not support the HTTP protocol (e.g. FTP server)
  • 403 Forbidden, if the current logged user has not the correct rights to use the proxy service
  • 406 Not Acceptable, if the type (mime-type) of the requested resource is not supported by the proxy (e.g. binary file. See also the proxy configuration parameters.
  • 500 Internal Server Error, if some internal server errors have occurred
  • Other HTTP status codes returned by the server that host the resource identified by the specified ENCODED_URL parameter
POST /favorites

This API provides a storage for general data mapping the data itself with a key called favorites. The data must be sent as payload. The API is independent from the sent data format.

Request Payload
  • Data to store
Returned Status Code
  • 200 OK, in case of success
  • 400 Bad Request, if the payload is not specified or is not valid
  • 403 Forbidden, if the current logged User has not the correct rights to use the general storage service
  • 503 Forbidden, if the user is not logged and the authentication in the Annotation Server is enabled
  • 500 Internal Server Error, if some internal server errors have occurred

GET /favorites

This API return all stored data mapped with the key favorites related to the current logged user (if the authentication is enabled) or to the anonymous user.

Output Data Formats
  • Any (the client have to interpret the data)
Returned Status Code
  • 200 OK, in case of success
  • 204 No Content, if no data has been mapped with the key favorites
  • 403 Forbidden, if the current logged User has not the correct rights to use the general storage service
  • 503 Forbidden, if the user is not logged and the authentication in the Annotation Server is enabled
  • 500 Internal Server Error, if some internal server errors have occurred