Introduction

This is the developer documentation for the Piscatus REST API (also known as the API). The API allows integrators to retrive information from the Piscatus document archive.

The API is based on REST principles You can use pretty much any HTTP client in any programming language to interact with the API.

If you have any problems or requests please contact info@piscatus.se.

Conventions

Here you’ll find the various standards and conventions the Piscatus API expect as input/output when talking to the resources.

If a supplied input parameter doesn’t adhere to the format used by Piscatus the request will be denied with an appropriate error message.

Dates

Piscatus encodes and decodes all dates as in the format like YYYY-MM-DD, example 1970-01-01 where:

UTF-8 encoding

Every string passed to and from the Piscatus API needs to be UTF-8 encoded.

National Identification Number

National identification numbers for persons and companies are in the format YYMMDD-XXXX.

Interacting with the API

All API accesses are performed over HTTPS through api.piscatus.se and data is sent and received as JSON encoded text. Responses to GET request can be sent as JSONP if a callback parameter is passed.

In order to ensure data privacy the following choices have been made, to name the some that directly impact API workflows:

HTTP Verbs

The Piscatus API use appropriate HTTP verbs for each action. The terms verb and method are used interchangingly.

Read more about HTTP/1.1 Method Definitions.

URL Components

When constructing resource identifiers (which are regular URIs) it is best to consider them as being built with up to four discrete units. An exception to this rule is the collection of utility resources; one of them being the authentication resource found at ENDPOINT/auth.

Endpoint: https://api.piscatus.se/VERSION

Actor resource / Utility resources: /ACTOR[/KEY] or /UTILITY[/...]

Object resource: /COLLECTION[/KEY]

Parameters: /?QUERYSTRING

Note: The Actor/Utility and Object components depend on the component listed before them, respectively.

Unit Fields

The units have parameterized fields, which allow you to change their respective meanings, those fields are briefly described below.

VERSION: Current and only API version is v1.

ACTOR: Actors are the data owners.

KEY: The identifier of an object in a collection.

QUERYSTRING: A set of key-value pairs, used for filtering.

Resource Types

There are three main types of resources - objects, collections of objects and utilities.

It can generally be said that if a URL ends with a unique identifier (also known as a key), it is an object or a sub-object. Resources ending with collection names are collection resources. Utilities exist alongside the regular resources.

Object Resources

Objects are mostly real-world things, such as document.

An example: /docs/1028271a4913b270df2fdaeadff09205

Collection Resources

Collections are conceptually lists of objects, that can be queried. When a collection resource is queried it will only return partial objects. If you want to see the actual objects you have to call the object resource.

An example: /docs

Filters

When searching for an object, it is suggested that you list the appropriate collection and add query parameters for the features of the object(s) you are trying to find in the URL.

An example: /docs?query=Piscatus

Utility Resources

Utilities are defined on a per-resource basis, but their responsibilities vary from case to case.

An example: /auth

Actor Resources

Actor resources are a more specific case of collection and object resources, they represent the data owners within the system. Currently there are no actors resources.

API

/docs

The /docs resource represents the collection of documents.

URL Structure

https://api.piscatus.se/v1/docs

Input

Parameter Description
query OPTIONAL, search query [1]
nin OPTIONAL, National Identification Number, can both be a personal identification number or a company identifier [1]
agent OPTIONAL, agent identifier [5]
begin-date OPTIONAL, begin date filter [3]
end-date OPTIONAL, end date filter, should be larger than begin-date [4]
start-index OPTIONAL, the start index of documents found [5]
authority OPTIONAL, Authority ID

[1] : If both these are passed, nin is omitted.

[2] : If nin or query is passed as well, they are omitted. Only applicable if the user owns the requested agent.

[3] : Defaults to the beginning of time.

[4] : Defaults to todays date.

[5] : Defaults to zero (0).

Output

Parameter Description
count Total numbers of documents found
+ documents The list of document objects
_ id Document key
_ date Date document was added to system
_ historic_date Date if being a historic document
_ actors Number of actors in the document
_ pages Number of pages in the document
_ filename Name of file
_ file_size File size in bytes
_ authority_id Authority (ID) the document was received from
_ authority_name Authority (name) the document was received from
_score Relevance (the higher the more weight). Only returned when query parameter is passed in the request.

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/docs \
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    count: 1,
    documents:
    [
        {
            "id": "1028271a4913b270df2fdaeadff09205",
            "date": "2012-01-01",
            "historic_date": "0000-00-00",
            "actors": 1,
            "pages": 1,
            "filename": "file.pdf",
            "file_size": 1024,
            "authority_id": 1,
            "authority_name": "Stockholms stad"
        }
    ]
}

/docs/<id>

The /docs/<id> is the object resource of documents.

URL Structure

https://api.piscatus.se/v1/docs/<id>

Input

Parameter Description
id Document identifier

Output

Parameter Description
id Document identifier
date Date document was added to system
historic_date Date if being a historic document
pages Number of pages in the document
filename Name of file
file_size File size in bytes
authority_id Authority (ID) the document was received from
authority_name Authority (Name) the document was received from
actors List of actors in the document
affected_authorities List of affected authorites in the document

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/docs/1028271a4913b270df2fdaeadff09205 \
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "id": "1028271a4913b270df2fdaeadff09205",
    "date": "2012-01-01",
    "historic_date": "0000-00-00",
    "pages": 1,
    "filename": "file.pdf",
    "file_size": 1024,
    "authority_id": 1,
    "authority_name": "Stockholms stad",
    "actors": ["430101-3787"],
    "affected_authorities": ["Stockholms stad"]
}

/docs/<id>/file

The /docs/<id>/file resource lets you read the raw document.

URL Structure

https://api.piscatus.se/v1/docs/<id>/file

Input

Parameter Description
id Document identifier

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/docs/1028271a4913b270df2fdaeadff09205/file \
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 1024
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Cache-Control: public
Content-Description: File Transfer
Content-Disposition: attachment; filename=file.pdf
Content-Transfer-Encoding: Binary
Connection: keep-alive

...

/authorities

The /authorities resource represents the collection of authorities handled by the system.

URL Structure

https://api.piscatus.se/v1/authorities

Output

Parameter Description
+ authorities List of authorities
_ id Authority identifier
_ name Authority name
_ subcategory Belongs to subcategory
+ categories List of categories
_ id Category identifier
_ name Category name
+ subcategories List of subcategories
_ id Subcategory identifier
_ name Subcategory name
_ category Belongs to catefory

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/authorities \
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "authorities":
    [
        {
            "id": 1,
            "name": "Stockholms stad",
            "subcategory": 1
        },
        ...
    ],
    "categories":
    [
        {
            "id": 1,
            "name": "Kommuner",
        },
        ...
    ],
    "subcategories":
    [
        {
            "id": 1,
            "name": "Stockholms lan",
            "category": 1
        },
        ...
    ]
}

/agents

The /agents is the collection resource of agents. The actor is passed in the authorization header.

URL Structure

https://api.piscatus.se/v1/agents

Output

Parameter Description
count Total numbers of agents found
agents List of agents
_id Agent identifier
_title Title of the agent

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/agents \
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "count": 1,
    "agents":
    [
        {
            "id": 1,
            "title": "Agent 1"
        }
    ]
}

/agents/<id>

The /agents<id> is the object resource of agents. The actor is passed in the authorization header.

URL Structure

https://api.piscatus.se/v1/agents/<id>

Input

Parameter Description
id Agent identifier

Output

Parameter Description
id Agent identifier
title Title of the agent
send_email If e-mail alarms are sent
type Agent type. Could be nin or freetext

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/agents/1 \
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "id": 1,
    "title": "Agent 1",
    "send_email": "true",
    "type": "nin"
}

/agents/<id>/targets

The /agents/<id>/targets is the collection resource of agent targets. The actor is passed in the authorization header.

URL Structure

https://api.piscatus.se/v1/agents/<id>/targets

Input

Parameter Description
id Agent identifier

Output

Parameter Description
count Total numbers of agents found
targets List of targets
_id Target identifier
_target National Identification Number or freetext search query
_comment Target comment

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/agents/1/targets \
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "count": 2,
    "targets":
    [
        {
            "id": 1,
            "target": "YYMMDD-XXXX",
            "comment": "Person 1"
        },
        {
            "id": 2,
            "target": "YYMMDD-XXXX",
            "comment": "Person 2"
        }
    ]
}

/agents/<agent-id>/targets/<target-id>

The /agents<agent-id>/targets/<target-id> is the object resource of targets. The actor is passed in the authorization header.

URL Structure

https://api.piscatus.se/v1/agents/<agent-id>/targets/<target-id>

Input

Parameter Description
agent-id Agent identifier
target-id Target identifier

Output

Parameter Description
id Target identifier
target National Identification Number or freetext search query
comment Target comment

Example

$ curl -i -X GET -H 'Authorization: token ...' https://api.piscatus.se/v1/agents/1/targets/1 \
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "id": 1,
    "target": "YYMMDD-XXXX",
    "comment": "Person 1"
}

/auth

The /auth resource is the authentication and authorization endpoint. Please see the Authentication chapter for details on how to authenticate and authorize.

API Response

By default the Piscatus API returns JSON. We encourage you to use JSON.

HTTP Headers

The Piscatus API returns standard HTTP header information with all of its responses.

HTTP Status Codes

The Piscatus API will return appropriate HTTP Status Codes for every request.

Code Text Description
200 OK Success
400 Bad Request The request cannot be fulfilled due to bad syntax
401 Unauthorized The Request was either not authorized or did have wrong credentials
403 Forbidden The request is understood, but it has been refused
404 Not Found The requested resource could not be found at the given URI
413 Request Entity Too Large The request is larger than the server is willing or able to process
414 Request-URI Too Long The URI provided was too long for the server to process
429 Too Many Requests The user has sent too many requests to the resource in a given amount of time.
500 Internal Server Error Something is broken on our end
502 Bad Gateway Piscatus API is down or being upgraded
503 Service Unavailable The Piscatus API is up, but overloaded with requests

Error Messages

At some occasions the Piscatus API returns error messages. These are in JSON format.

Example

{
    "error": "access_denied"
}

Authentication

Piscatus uses Oauth2 for authentication throughout it’s API and requires authentication and authorization before issuing requests to any resource.

All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

Read more about OAuth2.

Basics

When accessing the Piscatus API applications must follow the same high level basic pattern which consists of four steps.

1. Register Client

Every Client that access the Piscatus API must register. Once registered you will receive necessary information needed for authentication with the Piscatus Authorization Server. Such as client_id, client_secret, etc.

2. Obtain an Access Token from the Piscatus Authorization Server

Before your client can access the Piscatus API it must exchange it’s credentials for an Access Token. The set of resources and operations permitted by an access token is controlled during the access token request via a variable parameter called ‘scope’. The way in how a client obtains an access token depends on the flow being used.

3. Issue an request using the Access Token

Once a client has retrieved an access token it can use that token to access the Piscatus API. Access Tokens have a limited life time after which they need to be refreshed or a new authorization needs to be made. An access token is associated with a scope that is either a default scope or a scope requested by the client. Access tokens are sent to the Piscatus API in the HTTP Authorization header, or as a query string parameter (if HTTP header operations are not available).

The HTTP Authorization header has the form of:

Authorization: token <Access Token>

The query string parameter has the form of:

https://<URI>?access_token=Access Token>

where <Access Token> is replaced with the current Access Token, i.e. Uv3P2UAjkSCNBIMhEGnz48iGQlM9pQq5

The default life time for an Access Token is 3600 seconds or 1 hour.

Example

To issue a request with a retrieved Access Token of RHLeJsE5KwpPWF6FMWrXttiISJ6I3WwY

curl -i -X GET \
-H "Authorization: token RHLeJsE5KwpPWF6FMWrXttiISJ6I3WwY" \
https://api.piscatus.se/v1/RESOURCE
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
    Connection: keep-alive

{
        "hello": "world"
}

Format

Piscatus accepts the application/x-www-form-urlencoded media type for POST payload. The result is however always JSON formatted.

Authentication Flows

Piscatus supports the two major flows listed in the specification. They are explained in more detail below.

Protocol Flow

The abstract OAuth 2.0 flow is illustrated below

 +--------+                               +---------------+
 |        |--(A)- Authorization Request ->|   Resource    |
 |        |                               |     Owner     |
 |        |<-(B)-- Authorization Grant ---|               |
 |        |                               +---------------+
 |        |
 |        |                               +---------------+
 |        |--(C)-- Authorization Grant -->| Authorization |
 | Client |                               |     Server    |
 |        |<-(D)----- Access Token -------|               |
 |        |                               +---------------+
 |        |
 |        |                               +---------------+
 |        |--(E)----- Access Token ------>|    Resource   |
 |        |                               |     Server    |
 |        |<-(F)--- Protected Resource ---|               |
 +--------+                               +---------------+

A. The client requests authorization from the resource owner. The authorization request can be made directly to the resource owner (as shown), or preferably indirectly via the authorization server as an intermediary. B. The client receives an authorization grant, which is a credential representing the resource owner’s authorization. The authorization grant type depends on the method used by the client to request authorization and the types supported by the authorization server. C. The client requests an access token by authenticating with the authorization server and presenting the authorization grant. D. The authorization server authenticates the client and validates the authorization grant, and if valid issues an access token. E. The client requests the protected resource from the resource server and authenticates by presenting the access token. F. The resource server validates the access token, and if valid, serves the request.

Resource Owner Password Credentials Grant

The resource owner password credentials grant type is suitable in cases where the resource owner has a trust relationship with the client, such as the device operating system or a highly privileged application.

The advantage over HTTP Basic, is that the user credentials are used in a single request and are exchanged for an access token. This eliminates the need to store the username and password.

Unlike the Authorization- and Implicit flow there are no redirects because the user provides their username and password directly. The access token is also provided immediately and there’s no authorization code which must be exchanged for an access token.

 +----------+
 | Resource |
 |  Owner   |
 |          |
 +----------+
      v
      |    Resource Owner
     (A) Password Credentials
      |
      v
 +---------+                                  +---------------+
 |         |>--(B)---- Resource Owner ------->|               |
 |         |         Password Credentials     | Authorization |
 | Client  |                                  |     Server    |
 |         |<--(C)---- Access Token ---------<|               |
 |         |    (w/ Optional Refresh Token)   |               |
 +---------+                                  +---------------+

A. The resource owner provides the client with its username and password. B. The client requests an access token from the authorization server’s token endpoint by including the credentials received from the resource owner. When making the request, the client authenticates with the authorization server. C. The authorization server authenticates the client and validates the resource owner credentials, and if valid issues an access token.

To gain an access token, the client make a POST request to the Piscatus Authentication Server with the users authentication parameters placed in the request body. The grant_type parameter must be set to password.

Input

Parameter Description
grant_type Must be set to password
username The username, typically email
password The password associated with this account
scope OPTIONAL, set of permissions the client requests

Output

Parameter Description
access_token The access token issued
expires_in Number of seconds before this access token expires, typically 3600 seconds
token_type set to bearer
scope OPTIONAL, set of permissions the client receives

Example

$ curl -i -X POST https://api.piscatus.se/v1/auth \
    -d "grant_type=password&username=chris&password=god&scope=user.*"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "access_token": "RHLeJsE5KwpPWF6FMWrXttiISJ6I3WwY",
    "expires_in": "3600",
    "scope": "user.*",
    "token_type": "bearer"
}

Client Credentials Grant

The Client Credentials Grant flow is suitable for server side clients that acts on a service level. i.e. not on the behalf of a user. The client credentials grant type is only available for confidential clients and must be granted this permission when registering.

Like the Resource Owner Password Credential Grant flow there are no redirects, the client supplies it’s credentials directly. The access token is also provided immediately and there’s no authorization code which must be exchanged for an access token.

 +---------+                                  +---------------+
 |         |                                  |               |
 |         |>--(A)- Client Authentication --->| Authorization |
 | Client  |                                  |     Server    |
 |         |<--(B)---- Access Token ---------<|               |
 |         |                                  |               |
 +---------+                                  +---------------+

A. The client authenticates with the authorization server and requests an access token from the token endpoint. B. The authorization server authenticates the client, and if valid issues an access token.

To gain an access token, the client make a POST request to the Piscatus Authentication Server with the clients authentication parameters placed as a Basic Authorization in the header. The grant_type parameter must be set to client_credentials.

The HTTP Basic Auth header has the form of:

Authorization: Basic base64(client_id + ":" + client_secret)

For instance, a client with the identifier client1 and secret secret123 would identify with:

Authorization: Basic Y2xpZW50MTpzZWNyZXQxMjM=

Input

Parameter Description
grant_type Must be set to client_credentials
scope OPTIONAL, set of permissions the client requests

Output

Parameter Description
access_token The access token issued
expires_in Number of seconds before this access token expires, typically 3600 seconds
token_type set to bearer
scope OPTIONAL, set of permissions the client receives

Example

$ curl -i -X POST \
 -H "Authorization: Basic Y2xpZW50MTpzZWNyZXQxMjM=" \
 -d "grant_type=client_credentials&scope=client.*" \
  https://api.piscatus.se/v1/auth
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 100
Date: Tue, 01 Jan 2013 08:00:00 GMT
Server: Cowboy
Connection: keep-alive

{
    "access_token": "RHLeJsE5KwpPWF6FMWrXttiISJ6I3WwY",
    "expires_in": "3600",
    "scope": "client.*",
    "token_type": "bearer"
}