Unlock - Unlock Text: API Documentation

API Documentation

POST User

When applied to a User resource the POST operation will create a new User resource under the /users/ collection resource.

Sample Request: Create User

$ curl -i -X POST http://unlock.edina.ac.uk/text-api/users/edina \
> -H 'Accept: application/json' \
> -H 'Authorization: mykey'

Sample Response: Create User

HTTP/1.1 201 CREATED
Date: Fri, 18 Nov 2011 15:51:47 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
    "UserId":"edina",
    "Uri":"http://unlock.edina.ac.uk/text-api/users/edina",
    "User-Key":"mykey" 
}

Request Parameters

None

Request Headers

Header

Description

Accept

Specifies the format that the client can accept in response. Currently only application/json is supported. The wildcards *.*, application/* are also accepted in which case the output format will default to application/json. If any other format is specified an HTTP response code 406 "Not Acceptable" is returned with no entity body.

Authorization
[Required]

Specifies a user key to be associated with a User resource. A User resource cannot successfully be created without supplying a value for this header.

Any Batch Job or Text resources created by a user with a user key supplied as the Authorization request header are considered protected and subsequent request for these resources require the inclusion of the correct user key in the Authorization header.

Response Headers

Header	Description
`Content-Type`	The mime type of the body contetnt of the response. Currently `application/json` is the only supported Content-Type.

GET User

When applied to a User resource the GET operation will return a response that indicates if the user exists or not. Additionally, when the request parameter stats and an Authorization request header containing a valid user key are supplied, statistics about the requested user resource can be obtained.

Sample Request: Check User Exists

$ curl -i -X GET http://unlock.edina.ac.uk/text-api/users/edina \
> -H 'Accept: application/json'

Sample Response: Check User Exists

HTTP/1.1 200 OK
Date: Mon, 21 Nov 2011 15:00:44 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

200 Ok

Sample Request: Get User Statistics

$ curl -i -X GET http://unlock.edina.ac.uk/text-api/users/edina?stats=true \
> -H 'Accept: application/json' \
> -H 'Authorization: mykey'

Sample Response: Get User Statistics

HTTP/1.1 200 OK
Date: Mon, 21 Nov 2011 15:07:23 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
    "UserCreated": "Thu, 17 Nov 2011 16:11:32 +0000",
    "NumberofActiveBatchJobs": 1,
    "NumberOfActiveTexts": 1,
    "TotalBatchJobsParsed": 1,
    "TotalTextsParsed": 1,
    "LastBatchJobPOST": "Thu, 17 Nov 2011 16:11:51 +0000"
}

Request Parameters

stats: true/false
include stats on user resource such as number of Batch Job resources, number of Text resources completed, etc. If stats parameter is set to true then a valid user key must be provided as the Authorization header of the request.

Request Headers

Header	Description
`Accept`	Specifies the format that the client can accept in response. Currently only `application/json` is supported. The wildcards `.`, `application/*` are also accepted in which case the output format will default to `application/json`. If any other format is specified an HTTP response code `406 "Not Acceptable"` is returned with no entity body.
`Authorization`	Specifies a user key associated with a User resource. User statistics require the submission of a valid user key as the value for this header.

Response Headers

Header	Description
`Content-Type`	The mime type of the body contetnt of the response. Currently `application/json` is the only supported Content-Type.

POST Batch Job

When applied to the URI pattern */batchjobs, the POST operation will create a new Batch Job resource. If any Text elements are included within the body of the request, corresponding Text resources will also be created, subordinate to the Batch Job resource. If the Batch Job resource already exists or any texts within the request body are not unique the Batch Job and Text objects will not be created and an error message with appropriate response code will be returned to the client. A valid request will return immediately with a 202 "Accepted" response code. This is because it might take some time to process and create the Text resource.

Sample Request: Create Batch Job

$ curl -i -X POST http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh \
> -H 'Accept: application/json' \
> -H 'Authorization: mykey'

Sample Response: Create Batch Job

HTTP/1.1 202 ACCEPTED
Date: Tue, 22 Nov 2011 16:09:21 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
"batch-id":"edinburgh",
"Created": "Nov. 22, 2011, 4:09 p.m.",
"User":"edina",
"Texts":[
        ]
}

Sample Request: Create Batch Job with Subordinate Texts

$ curl -i -X POST http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh \
> -H 'Accept: application/json' \
> -H 'Authorization: mykey' \
> -H 'Content-Type: application/json' \
> -d '{"Texts":[{"src":"http://www.ed.ac.uk/home/"},{"src":"http://www.edinburgh.org/"}]}'

Sample Response: Create Batch Job with Subordinate Texts

HTTP/1.1 202 ACCEPTED
Date: Tue, 22 Nov 2011 16:09:21 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
"batch-id":"edinburgh",
"Created": "Nov. 22, 2011, 4:09 p.m.",
"User":"edina",
"Texts":[
        {
        "src":"http://www.ed.ac.uk/home/",
        "resource-id":"edinburgh1",
        "resource-uri":"http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh1",
        "status":"pending",
        "output":[
        ]
    },
        {
        "src":"http://www.edinburgh.org/",
        "resource-id":"edinburgh2",
        "resource-uri":"http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh2",
        "status":"pending",
        "output":[
        ]
    }
        ]
}

Request Parameters

None

Request Headers

Header

Description

Accept

Authorization

Valid user key for the supplied User resource.

Optional header which, if used, will mean that any subsequent operations on the created Batch Job resource (or on any subordinate Text resources) will require a matching Authorization header.

Content-Type

If the request body has content (i.e. list of Text resources) then the Content-Type must be specified. The API currently accepts application/json. The wildcards *.*, application/* are also accepted in which case the Content-Type will default to application/json. If another unsupported content type is specified an HTTP response code 415 "Unsupported Media Type" is returned to client. Note this header only applies to the format in request body and does not have any bearing on the format of any outputs generated by the request.

Response Headers

Header	Description
`Content-Type`	The mime type of the body contetnt of the response. Currently `application/json` is the only supported Content-Type.

GET Batch Job

When applied to a Batch Job resource the GET operation will return a list of references to Text resources within the Batch Job, if any are available.

Sample Request: Get Batch Job Status Update

$ curl -i -X GET http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh \
> -H 'Accept: application/json' \
> -H 'Authorization: mykey'

Sample Response: Get Batch Job Status Update

HTTP/1.1 200 OK
Date: Wed, 23 Nov 2011 12:06:12 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
"batch-id":"edinburgh",
"Created": "Nov. 22, 2011, 4:09 p.m.",
"User":"edina",
"Texts":[
        {
        "src":"http://www.ed.ac.uk/home/",
        "resource-id":"edinburgh1",
        "resource-uri":"http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh1",
        "status":"complete",
        "output":[
            "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh1.xml",
            "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh1.json",
            "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh1.kml"
        ]
    },
        {
        "src":"http://www.edinburgh.org/",
        "resource-id":"edinburgh2",
        "resource-uri":"http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh2",
        "status":"complete",
        "output":[
            "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh2.xml",
            "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh2.json",
            "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh2.kml"
        ]
    }
        ]
}

Request Parameters

None

Request Headers

Header

Description

Accept

Authorization

Valid user key for the supplied User resource.

Only needed if the Batch Job was created with a user key. If the Batch Job was created with a user key and no user key is provided or the incorrect user key is provided an HTTP response code 403 "Forbidden" is returned. If the Batch Job was NOT created with a user key the Authorization header is ignored.

Response Headers

Header	Description
`Content-Type`	The mime type of the body contetnt of the response. Currently `application/json` is the only supported Content-Type.

GET Batch Jobs

The GET operation will return a list of Batch Jobs, if any are available. This request is made in conjunction with a User resource to return a list of Batch Jobs related to that user.

Sample Request: List User's Batch Jobs

$ curl -i -X GET http://unlock.edina.ac.uk/text-api/users/edina/batchjobs \
> -H 'Accept: application/json'

Sample Response: List User's Batch Jobs

HTTP/1.1 200 OK
Date: Wed, 23 Nov 2011 14:39:07 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
"Batch Jobs":[
        {       
                "batch_id":"edinburgh",
                "batch-uri":"http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh", 
                "Created":"Nov. 22, 2011, 4:09 p.m.",
                "User":"edina"
        }
        ]  
}

Request Parameters

None

Request Headers

Header	Description
`Accept`	Specifies the format that the client can accept in response. Currently only `application/json` is supported. The wildcards `.`, `application/*` are also accepted in which case the output format will default to `application/json`. If any other format is specified an HTTP response code `406 "Not Acceptable"` is returned with no entity body.

Response Headers

Header	Description
`Content-Type`	The mime type of the body contetnt of the response. Currently `application/json` is the only supported Content-Type.

POST Text

When applied to the URI pattern */text, the POST operation will create a new Text resource. If the Text resource already exists the Text object will not be created and an error message with appropriate response code will be returned to the client. A valid request will return immediately with a 202 "Accepted" response code. This is because it might take some time to process and create the Text element.

Sample Request: Create Text

$ curl -i -X POST http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/text \
> -H 'Accept: application/json' \
> -H 'Authorization: mykey' \
> -H 'Content-Type: application/json' \
> -d '{"src":"http://edina.ac.uk"}'

Sample Response: Create Text

HTTP/1.1 202 ACCEPTED
Date: Wed, 23 Nov 2011 16:11:51 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
    "src":"http://edina.ac.uk",
    "resource-id":"edinburgh3",
    "resource-uri":"http://unlock.edina.ac.uk/gp-test/users/edina/batchjobs/edinburgh/edinburgh3", 
    "output":[
    ]
}

Request Parameters

None

Request Headers

Header

Description

Accept

Authorization

Valid user key for the supplied User resource.

Optional header which, if used, will mean that any subsequent operations on the created Text resource will require a matching Authorization header.

Content-Type

If the request body has content (i.e. a Text resources) then the Content-Type must be specified. The API currently accepts application/json. The wildcards *.*, application/* are also accepted in which case the Content-Type will default to application/json. If another unsupported content type is specified an HTTP response code 415 "Unsupported Media Type" is returned to client. Note this header only applies to the format in request body and does not have any bearing on the format of any outputs generated by the request.

Response Headers

Header	Description
`Content-Type`	The mime type of the body contetnt of the response. Currently `application/json` is the only supported Content-Type.

GET Text

When applied to a Text resource the GET operation will return a responde code signifying the processing progress of the resource and, if complete details of the Text and what output formats it is available as.

Sample Request: Get Text Status

$ curl -i -X GET http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh3 \
> -H 'Accept: application/json' \
> -H 'Authorization: mykey'

Sample Response: Get Text Status

HTTP/1.1 200 OK
Date: Thu, 24 Nov 2011 10:00:43 GMT
Server: Apache/2.2.13 (Unix) mod_wsgi/2.5 Python/2.6.2 mod_jk/1.2.28
Transfer-Encoding: chunked
Content-Type: application/json

{
    "src":"http://edina.ac.uk",
    "resource-id":"edinburgh3",
    "resource-uri":"http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh3", 
    "output":[
        "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh3.xml",
        "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh3.json",
        "http://unlock.edina.ac.uk/text-api/users/edina/batchjobs/edinburgh/edinburgh3.kml"
    ]
}

Request Parameters

None

Request Headers

Header

Description

Accept

Authorization

Valid user key for the supplied User resource.

Only needed if Text (or enclosing Batch Job) was created with user key. If the Text was created with a user key and no user key is provided or the incorrect user key is provided an HTTP response code 403 "Forbidden" is returned. If the Text was NOT created with a user key the Authorization header is ignored.

Response Headers

Header	Description
`Content-Type`	The mime type of the body contetnt of the response. Currently `application/json` is the only supported Content-Type.