Core API

EPIC Web Service API Definition

Copyright: © 2009-2011 SARA Computing and Networking Services
  License: Creative Commons Attribution - Share Alike 3.0 Unported
   Status: Draft
  Version: 0.7
  Authors: Pieter van Beek, SARA
           Eric Auer, MPI Nijmegen
           Hennie Brugman, Meertens Instituut

Abstract

This document proposes a common interface for RESTful web service implementations (simply called "the interface" or "the API" hereafter) built around the Handle System. TODO @Hennie: complete this abstract. -PieterB

Introduction

TODO: @Hennie: introductie -PieterB

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC2119.

This document describes a RESTful web service, using the HTTP/1.1 application protocol. The API strictly adheres to the rules of safety and idempotence laid out in §9.1 of RFC2616: GET is guaranteed to be both safe and idempotent; PUT and DELETE are idempotent, but not safe; POST is neither safe nor idempotent. Extension "POE" offers a method to circumvent the non-idempotence of the POST method.

Glossary

For clarity end brevity, some terms in this document have a very specific meaning:

the API: the Application Programming Interface laid out in this document
server, implementation: an implementation of the API
implementor: an entity that builds an implementation the API
(service) provider: an organisation or person that operates a server as a service
client: a piece of software that interacts with a server using the API
user: an organisation or person that operates a client

Representation

JSON was chosen as the primary representation of resources, that all servers MUST be able to produce and consume. Implementations may, however, be able to produce and consume more than one representation of a resource. Servers MAY be able to produce and consume additional representations, like XML or DER-encoded ASN.1. In order to promote interoperability, implementors SHOULD publish additional representations in extension documents as explained below. This document defines one additional representations: XHTML.

In order to promote consistency between representations and implementations, this paragraph contains three sections:

1. Atomic Types describes a set of simple atomic types that can be composed into more complex data structures.

2. JSON representations describes the way in which the atomic types are to be represented in JSON.

3. Abstract Data Model describes the complete data model of the service, in terms of atomic types.

Atomic Types

The following atomic types are used in the remainder of this document:

• A string is a sequence of zero or more Unicode characters.

• A blob is a sequence of octets.

• A number is a signed integer. Servers SHOULD support infinitely large integers. Servers MUST support 64-bit signed integers from ­–2⁶³ to 2⁶³–1 inclusive.

• A value is a string, blob, number, list or object.

• A list is an unordered list of values.

• An object is an unordered set of string→value-pairs with unique strings, also known as members.

• A collection is an unordered set of string→object-pairs, where the string is a segment-nz as defined in section 3.3 of RFC3986. See also the section on Resource Collections below.

Future extensions defining additional atomic types MUST specify how these additional atomic types are represented in all representations defined in this document and registered extensions.

JSON Representation

This API uses JSON as the primary exchange format. All implementations MUST be able to produce and consume JSON.

Representation of the atomic types is as follows:

• strings represented as JSON strings.

• blobs are represented as JSON strings, containing the base64-encoded octet stream.

• numbers are represented as JSON numbers.

• lists are represented as JSON arrays.

• objects and collections are represented as JSON objects.

For compatibility with a broad range of clients, implementations are encouraged to support MIME-types text/json and application/x-json as equivalent alternatives.

Abstract Data Model

Everything in this paragraph follows directly from RFC3651. It's only mentioned here for clarity, consistency and brevity in the remainder of this document.

naming authority

a string consisting of dot-seperated substrings of any Unicode character except dot '.' or slash '/'.

local name

a string of Unicode characters.

handle

a string consisting of a naming authority, a '/' character, and a local name. See §2 of RFC3651 for the syntax and semantics of a handle and its parts.

Recent versions of the Handle System provide the possibility of Template Handles. Naming Authorities that use Template Handles must define a Template Delimiter Character for their namespace, which devides handles into a base part and an extension part. CNRI suggests the use of the at-sign "@" as Template Delimiter Character. TODO This may no longer be accurate --Pieter van Beek 2012-02-09

value reference

a pointer to a Handle Value: a string consisting of the string representation of a non-negative number, a ':' character, and a handle. See §3 of RFC3651 for more information about value references.

value set

a collection with the following members:

• values/: a collection of handle values, indexed by the handle values' idx-member.
• handle: (if applicable) the handle that references this value set.

Extensions may define additional members.

handle value

a collection with at least the following members:

• type: A string consisting of a dot "." separated list of strings of any unicode character except ".". Specifies the data type of member data.

• data: a blob. Additionally, the following members MAY exist:

• idx: a positive number that specifies the unique index of this Handle Value within its Value Set.

• ttl: a number that specifies the Time-To- Live of the value record. A positive value defines the time to live in terms of seconds since 00:00:00 UTC, January 1st 1970. A negative value specifies the time to live in terms of the number of seconds elapsed since the value was obtained.

• timestamp: a number that records the last time this Handle Value was updated at the server. The field contains elapsed time since 00:00:00 UTC, January 1970 in milliseconds.

• refs: a list of references to other Handle Values.

• parsed/: depends on the value of type: by default, parsed/ is unset. However, some of the pre-defined handle types are represented (in the Handle System) as a binary encoded structured value. In these cases, parsed/ MUST contain a decoded representation of the structured value. In particular:

  • if type == "HS_VLIST", then parsed/ contains a collection of references as described in §3.2.7 of RFC3651.
    • if a reference points to a Handle Value controlled by the server, then it's indexed by URIref.
    • otherwise, it's indexed by URI http://hdl.handle.net/«handle»?index=«idx»
  • if type == "10320/loc", then parsed/ contains a collection with the following members (see 10320/loc for details):
    • chooseby: (optional) a list of strings. Defaults to ["locatt","country","weighted"] when omitted.
    • locations/: a collection of the following members, indexed by href, URI-escaped as explained in section NamingAuthorities and Suffixes in Path Segments:
      • href: a URI.
      • weight (optional): a number.
      • ...: type string: any other attributes of the element, if present.
    • ...: type string: other attributes (unescaped) of the element, if present.
  • other Handle Value Types (if not hidden by the server) such as HS_SITE, HS_PUBKEY, HS_SECKEY and HS_SERV MUST have decoded representations as well.

Extensions may define additional members.

The Handle System comes with its own authorization scheme. Services which do not respect this scheme SHOULD NOT relay any Handle Values or other information related to this scheme, such as HS_ADMIN values or the bit-mask described in §3.1 of RFC3651. Services which do respect the native Handle System authorization scheme SHOULD implement Extension 1.

Multistatus

Iets over multipart/mixed for returning multiple statuses. -Pieter van Beek 10/25/11 11:30 AM

Iets over batch operaties, waarvoor ze wel en niet bedoeld zijn, alternatieven, usecases -Pieter van Beek 2/3/11 4:28 PM

This data type is only of importance to clients and servers that wish to use batch-wise operations which may affect multiple resources. In response to an HTTP-request that triggers such an operation, the server MUST respond with HTTP/1.1 207 Multistatus, and return a representation of a multistatus object, explaining which resources were affected and/or which errors occured. If an operation is defined as being atomic, and errors occur for some URIs targeted by the request, then the operation must fail entirely. Resources which failed to be affected because other resources failed to be affected within the same atomic request MUST fail with status HTTP/1.1 424 Failed Dependency as defined in RFC4918.

A multistatus is a list of collections with the following members:

• baseuri: (optional) the base URIref to be used when interpreting the URIrefs in member href. Normally, this is the URI of the resource that spawned the asynchronous process.
• href: a list of one or more URIrefs which have been affected by the operation.
• status: a number: the HTTP/1.1 status code returned by the resource(s) in href.
• error: (optional) a list of pre-defined error condition strings, specifying the error(s) that occured during processing, if any.
• responsedescription: (optional) a human-readable string, describing what happened.
• location: (optional, implies only one entry in href) the Location: response header that was returned by the one resource in href.

Those familiar with WebDAV will recognise the structure of an XML -element as described in §13 of RFC4918.

Example

The clients submit the following batch request, which should affect multiple resources:

POST /NAs/10/handles/
Host: example.com
Content-Type: application/json
...

[ { "handle" : "handleOne",
    "values/": { "1": { "type": "URL",
                        "data": "http://www.example.com" } } },
  { "handle" : "handleTwo",
    "values/": { "1": { "type": "URL",
                        "data": "http://mail.example.com" } } } ]

The clients wants to affect two handles, with local names "handleOne" and "handleTwo" respectively. The server supports atomic batch operations, and replies responds as follows:

HTTP/1.1 207 Multistatus
Content-Type: application/json
...

[ { "href"  : "handleOne",
    "status": 403 },       /* HTTP/1.1 403 Forbidden */
  { "href"  : "handleTwo",
    "status": 424 } ]      /* HTTP/1.1 424 Failed Dependency */

For some reasen, the client didn't have permission to create/update the value set at /NAs/10/handles/handleOne. As a result, the resource at /NAs/10/handles/handleOne was unaffected as well, because the operation was defined as atomic.