apiary.apib

FORMAT: 1A
HOST: https://catalog.elog.io

# Catalog
A REST API for clients and third-party sites to interact with the data in the catalog.

The various objects and their properties are documented in much more detail here:
https://github.com/commonsmachinery/catalog/blob/master/doc/datamodel/core.md

The API uses many ideas from 
https://github.com/interagent/http-api-design and https://developer.github.com/v3/

Referenced objects are returned as a map:

    {
        "id": "someUserID",
        "href":  "https://catalog.elog.io/users/someUserID"
    }
    
When referencing another object in a PUT or POST request either property can be used for top-level objects,
but for e.g. `Media` objects that are referred via a `Work` only `href` is possible.


## Work [/works/{workID}{?fields,include,annotations}]
A work record.

The annotations, media and sources can either be manipulated via the sublist in the document, 
or via the separate collection endpoints.

Media instances are always accessed via the context of a Work, to determine visibility, 
and thus have URIs scoped under the work URI.
When adding another Work's Media to this Work, add the Work Media endpoint for that other
work to the `media` list.  It will be rewritten to the Media endpoint for the target Work.

To make the annotations easier to use in web pages the parameter `annotations` can be set
to a list of property names, e.g. `title,locator`.  This will change the response from a plain list to a map, only
including the listed properties.  (`all` means that all properties are included in the map.)
The keys in this map are the `propertyName`, and the value a list of the Annotations for
that property.  This allows easy access like `annotations.title[0].property.value` to show
e.g. a title without having to dig through the list.

The fields returned in the response can be selected with the `fields` parameter.

Some referenced objects can be populated in the response with the `include` parameter.  
(If `fields` has excluded the field, `include` will override and add the field to the response.)
The fields that can be populated are:

- `owner`: either `owner.user` or `owner.org`
- `added_by`
- `updated_by`

TODO: decide if more fields should be allowed to be populated.  The lists can be rather heavy.


+ Parameters
    + workID (string) ... Work record ID
    + fields (string, optional) ... Comma-separated list of top-level fields to include
        (filtering out all other fields), or exclude (if preceeded by `-`)
    + include (string, optional) ... Comma-separated list of subobjects to populate.
    + annotations (string, optional) ... Select properties to get or update.

+ Model
    + Headers

            Link: <https://catalog.elog.io/works/5396e592d7d163613d7321ee>;rel="self"

    + Body
    
            {
                "id": "5396e592d7d163613d7321ee",
                "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee",

                "added_by": {
                    "id": "someUserID",
                    "href":  "https://catalog.elog.io/users/someUserID"
                },
                "added_at": "2014-04-14T02:15:15Z",
                
                "updated_by": {
                    "id": "anotherUserID",
                    "href": "https://catalog.elog.io/users/anotherUserID"
                },
                "updated_at": "2014-04-14T02:15:15Z",
                
                "owner": {
                    "user": {
                        "id": "someUserID",
                        "href": "https://catalog.elog.io/users/someUserID"
                    }
                },
                
                "alias": "short-name",
                "description": "Description of work to guide catalog users (not part of the metadata)",
                "public": true,

                "forked_from": {
                    "id": "parentWorkID",
                    "href": "https://catalog.elog.io/works/parentWorkID"
                },

                "collabs": {
                    "users": [{
                        "id": "anotherUserID",
                        "href": "https://catalog.elog.io/users/anotherUserID"
                    }],
                    "groups": [{
                        "id": "someGroupID",
                        "href": "https://catalog.elog.io/groups/someGroupID"
                    }]
                },
                
                "annotations": [{
                        "id": "63613d7321ee5396e592d7d1",
                        "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/annotations/63613d7321ee5396e592d7d1",
                        
                        "updated_by": {
                            "id": "anotherUserID",
                            "href": "https://catalog.elog.io/users/anotherUserID"
                        },
                        "updated_at": "2014-04-14T02:15:15Z",
                        
                        "score": 100,
                        "property": {
                            "propertyName": "title",
                            "value": "Title of the work",
                            "titleLabel": "Title of the work"
                        }
                }],

                "sources": [{
                        "id": "6e592d7d63613d7321ee5391",
                        "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/sources/6e592d7d63613d7321ee5391",
                        
                        "source_work": {
                            "id": "sourceWorkID",
                            "href": "https://catalog.elog.io/works/sourceWorkID"
                        },
                        
                        "added_by": {
                            "id": "anotherUserID",
                            "href": "https://catalog.elog.io/users/anotherUserID"
                        },
                        "added_at": "2014-04-14T02:15:15Z"
                }],

                "media": [
                    {   "id": "someMediaID",
                        "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/media/someMediaID"
                    },
                    {   "id": "anotherMediaID",
                        "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/media/anotherMediaID"
                    }
                ]
            }


### Retrieve a Work [GET]
+ Response 200
    [Work][]


### Update a Work [PUT]
The following parameters can be updated, any others are ignored:

- alias
- description
- public

This really behaves like `PATCH`, so that any omitted parameters are not changed.

+ Request (application/json)

        {
            "alias": "foo",
            "description": "The foo movie",
            "public": true,
        }


+ Response 200 (application/json)
    [Work][]


### Update a Work [PATCH]

See `PUT` for details.

+ Request (application/json)

        {
            "public": true,
        }

+ Response 200 (application/json)
    [Work][]


### Delete a Work [DELETE]
+ Response 200
    [Work][]



## Work collection [/works{?page,per_page,sort,fields,include,annotations}]

### List Works [GET]
List all works visible to the current user, optionally applying paging, filters and sorting.

TODO: define filters and sorting.

Pagination is supported by returning a `Link` header with links according to 
http://tools.ietf.org/html/rfc5005

+ Parameters
    + page (number, optional) ... Page to start showing (first page has index 1)
    + per_page (number, optional) ... Page should contain these many records. Default and max values are system-dependent.
    + sort (string, optional) ... Sort response (see above). Default: "natural" sort.
    + fields (string, optional) ... Fields to include (see above)
    + include (string, optional) ... References to populate (see above)
    + annotations (string, optional) ... Select properties to get or update.

+ Response 200 (application/json)
    + Headers
    
            Link: <?offset=0&count=N&...>;rel="first", <?offset=Z&count=N&...>;rel="last", <?offset=X&count=N&...>;rel="previous", <?offset=Y&count=N&...>;rel="next"

    + Body
    
            []


### Create Work [POST]
Create a new work.  The following parameters are used, all others are included:

The following parameters are used when creating a Work:

- alias
- description
- public
- collaborators
- annotations (see below)
- sources (only source_work)
- media

If any fields are missing, they are set to empty values or lists.  
The default for `public` depends on system configuration.

+ Request (application/json)
    [Work][]
    
+ Response 201 (application/json)
    [Work][]


## Create Work from an uploaded file [/works/actions/upload{?email}]

Instead of extracting all the metadata from a file locally, the catalog may provide the
service to clients to upload files for server-side processing instead. This either requires an
active session for a user, or an email address to be provided in the request. In both cases an email
will be sent to the user when the file has been processed with a link to confirm the uploaded data.

### Upload file [POST]

TODO: is this a sane way to upload files, or should multi-part requests be used instead?
Or is this really up to the client's discretion and we should accept both?

+ Parameters
    + email (string, optional) ... Uploader email, if there isn't already an active user session.
    
+ Request (mime-type/of-file)

        <file contents>

+ Response 202 (application/json)

        { "confirm_email": "foo@example.org" }
        

## Create Work from an online source [/works/actions/fetch{?url,email}]

Similar to uploading a file, this fetches information about a work that's available at a URL online
and sends a confirmation email when the processing is finished.

### Fetch online source [POST]

+ Parameters
    + url (optional, string) ... The URL, if not specified in the request body.
    + email (string, optional) ... User email, if not specified in the request body and there isn't already an active user session.

+ Request (application/json)

        { "url": "http://some/where", "email": "foo@example.org" }
        
+ Request (application/x-www-form-urlencoded)

        url=http://some/where&email=foo@example.org

+ Response 202 (application/json)

        { "confirm_email": "foo@example.org" }



## Media [/works/{workID}/media/{mediaID}{?annotations,fields,include}]
A media instance, which is a read-only record of a particular media instance of a Work
at the time it was recorded in the catalog.

A given Media instance can be linked to multiple works (e.g. when a Work is forked, or just
if it is added multiple times by different people from the same media source).  The instances will
all have the same ID, but must always be accessed via one of the works to determine visibility.

To make the annotations easier to use in web pages the parameter `annotations` can be set
to a list of property names, e.g. `title,locator`.  This will change the response from a plain list to a map, only
including the listed properties.  (`all` means that all properties are included in the map.)
The keys in this map are the `propertyName`, and the value a list of the Annotations for
that property.  This allows easy access like `annotations.title[0].property.value` to show
e.g. a title without having to dig through the list.

Some referenced objects can be populated in the response with the `include` parameter.  
(If `fields` has excluded the field, `include` will override and add the field to the response.)
The fields that can be populated are:

- `added_by`

TODO: decide if more fields should be populated.


+ Parameters
    + fields (string, optional) ... Comma-separated list of top-level fields to include
        (filtering out all other fields), or exclude (if preceeded by `-`)
    + include (string, optional) ... Comma-separated list of subobjects to populate.
    + annotations (string, optional) ... Select properties to get or update in map.

+ Model
    + Headers
    
            Link: <https://catalog.elog.io/works/5396e592d7d163613d7321ee/media/6e1ee592539d7d163613d732>;rel="self"

    + Body

            {
                "id": "6e1ee592539d7d163613d732",
                "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/media/6e1ee592539d7d163613d732",
                
                "added_by": {
                    "id": "someUserID",
                    "href":  "https://catalog.elog.io/users/someUserID"
                },
                "added_at": "2014-04-14T02:15:15Z",
                
                "replaces": {
                    "id": "oldMediaID",
                    "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/media/oldMediaID"
                },

                "annotations": [{
                        "id": "63613d7321ee5396e592d7d1",
                        "property": {
                            "propertyName": "title",
                            "value": "Title of the work",
                            "titleLabel": "Title of the work"
                        }
                    }],
                "metadata": {
                        "xmp": "<?xml...",
                        "oembed": { "url": "http://some/photo.jpg" }
                    }
            }


### Retrieve a Media [GET]
+ Response 200 (application/json)
    [Media][]


### Unlink a Media from a Work [DELETE]
This does not delete the underlying Media instance, just the link to it.
If this was the last link to the Media, it will be garbage collected eventually.

+ Response 200
    [Media][]


## Media collection [/works/{workID}/media{?fields,include,annotations}]

All the Media instances linked to this work.

+ Parameters
    + workID (string) ... Work ID whose Media are manipulated
    + fields (string, optional) ... Fields to include (see above)
    + include (string, optional) ... References to populate (see above)
    + annotations (string, optional) ... Select properties to get in response.

### List Work Media [GET]
Return all Media instances of the Work.

+ Response 200 (application/json)

        [{ "id": "..." }, { "id": "..." }]
        

### Unlink all Media from a Work [DELETE]
Convenience method to unlink all medias, rather than one by one.

+ Response 200 (application/json)

        []
        


### Create or link a Media to an existing Work [POST]

If `href` is included, the referenced `Media` instance will be linked to this work.

Otherwise a new Media instance is created and linked to this work, 
using the following properties in the request:

- annotations (empty list if omitted)
- metadata (empty object if omitted)
- replaces (null if omitted)

+ Request (application/json)
    
        {
            "replaces": {
                "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/media/oldMediaID"
            },

            "annotations": [{
                    "property": {
                        "propertyName": "title",
                        "value": "Title of the work",
                        "titleLabel": "Title of the work"
                    }
                }],
            "metadata": {
                "oembed": { "url": "http://some/photo.jpg" }
            }
        }
    
+ Response 201 (application/json)
    [Media][]
        

## Create Media from an uploaded file [/works/{workID}/media/actions/upload]

Similar to creating a new Work from an uploaded file (see `POST /works/actions/upload`)
this creates a new Media instance for the file and links it to the work.

TODO: should return progress polling URL, or perhaps send an email when done.

### Upload file [POST]

TODO: is this a sane way to upload files, or should multi-part requests be used instead?  
Or is this really up to the client's discretion and we should accept both?

+ Request (mime-type/of-file)

        <file contents>

+ Response 202 (application/json)

        { }


## Create Media from an online source [/works/{workID}/media/actions/fetch{?url}]

Similar to creating a new Work from an online source (see `POST /works/actions/fetch`)
this creates a new Media instance for the file and links it to the work.

TODO: should return progress polling URL, or perhaps send an email when done.

### Fetch online source [POST]

+ Parameters
    + url (optional, string) ... The URL, if not specified in the request body.

+ Request (application/json)

        { "url": "http://some/where" }
        
+ Request (application/x-www-form-urlencoded)

        url=http://some/where

+ Response 202 (application/json)

        { }


## Annotation [/works/{workID}/annotations/{annotionID}]
A Work or Media annotation, based on the [W3C Ontology for media resources](http://www.w3.org/TR/mediaont-10/).
This maps format-specific metadata into a common set of properties.

Media objects also contain Annotations, but since Media are read-only there is no endpoint for manipulating 
that list.

+ Model
    + Headers

            Link: <https://catalog.elog.io/works/5396e592d7d163613d7321ee/annotations/63613d7321ee5396e592d7d1>;rel="self"

    + Body

            {
                "id": "63613d7321ee5396e592d7d1",
                "href": "https://catalog.elog.io/works/5396e592d7d163613d7321ee/annotations/63613d7321ee5396e592d7d1",
                
                "updated_by": {
                    "id": "anotherUserID",
                    "href": "https://catalog.elog.io/users/anotherUserID"
                },
                "updated_at": "2014-04-14T02:15:15Z",
                
                "score": 100,
                "property": {
                    "propertyName": "title",
                    "value": "Title of the work",
                    "titleLabel": "Title of the work"
                }
            }


### Get a Work Annotation [GET]
+ Response 200 (application/json)
    [Annotation][]


### Update an Annotation [PUT]
Only the `score` and `property` Annotation properties may be changed.
Only properties included in the request are changed.

+ Request (application/json)
    
        {
            "score": 47,
            "property": {
                "value": "A better title"
            }
        }

+ Response 200 (application/json)
    [Annotation][]


### Update an Annotation [PATCH]
Same as `PUT`.

+ Request (application/json)

        { "score": 47 }

+ Response 200 (application/json)
    [Annotation][]


### Delete an Annotation [DELETE]
+ Response 200
    [Annotation][]


## Work Annotation collection [/works/{workID}/annotations]
Endpoint for accessing all annotations for a Work.  To just read annotations, 
`Work.annotations` can be used instead.

### List Work Annotations [GET]
+ Response 200 (application/json)

        [{ "id": "..." }, { "id": "..." }]


### Add a Work Annotation [POST]
Only `score` and `property` are used from the request body.  

`property` must include at least `propertyName` and `value`.

If `score` is omitted it is calculated from `property`.

+ Request (application/json)

        {
            "property": {
                "propertyName": "title",
                "value": "A title"
            }
        }

+ Response 201 (application/json)
    [Annotation][]


### Delete all annotations for a Work [DELETE]
+ Response 200 (application/json)

        []


## Lookup works by URI [/lookup{?uri,offset,count,include}]

Lookup works based on a URI, typically either a URL denoting a web location
or a URN indicating a hash or other non-web identifier.

The best matches are always returned first.

Pagination is supported by returning a `Link` header with links according to 
http://tools.ietf.org/html/rfc5005

### Lookup by URI [GET]

+ Parameters
    + uri (string) ... A URI to lookup. Multiple URIs can be specified by repeating the parameter.
    + offset (number, optional) ... Skip this many records in the result. Default: 0
    + count (number, optional) ... Return this many records. Default and max values are system-dependent.
        If set to 1, it instructs that only the best Work object should be returned or a `404`, not a list of works.
    + include (string, optional) ... Which sublists to include in the response objects.
        See Work above for details.

+ Response 200 (application/json)
    + Headers
    
            Link: <?offset=0&count=N&...>;rel="first", <?offset=Z&count=N&...>;rel="last", <?offset=X&count=N&...>;rel="previous", <?offset=Y&count=N&...>;rel="next"

    + Body
    
            []


## Collection [/collections/{collectionID}]

TODO

## Collection collection [/collections]

TODO

## User [/users/{userID}]
Public user profiles.  `gravatar_email` is only visible to the users themselves, not to other users.
The other information is public.

+ Model
    + Header

            Link: <https://catalog.elog.io/users/5396e592d7d163613d7321ee>;rel="self"

    + Body

            {
                "id": "5396e592d7d163613d7321ee",
                "href": "https://catalog.elog.io/users/5396e592d7d163613d7321ee",
                
                "alias": "foobar",
                "profile": {
                    "name": "Foo Barson",
                    "email": "foo@example.org",
                    "location": null,
                    "website": "http://this/page",
                    "gravatar_email": "foo@example.org",
                    "gravatar_hash": "34cd643fb9230abe3"
                }
            }

### Get User profile [GET]
+ Response 200 (application/json)
    [User][]


### Update User profile [PUT]

`gravatar_hash` cannot be set directly, only via `gravatar_email`.  
Only the included properties are changed, as in `PATCH`.  
Set a property to `null` to remove the value.

+ Request
    
        {
            "alias": "new alias",
            "profile": {
                "gravatar_email": "other@example.org"
            }
        }

+ Response 200 (application/json)
    [User][]


### Update User profile [PATCH]

See `PUT`.

+ Request


        {
            "profile": {
                "name": "Foo G. Barson"
            }
        }

+ Response 200 (application/json)
    [User][]


## Organisation [/orgs/{orgID}]

TODO

## Organisation collections [/orgs]

TODO

## Group [/orgs/{orgID}/groups/{groupID}]

TODO

## Group collection [/orgs/{orgID}/groups]

TODO