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.
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.
Piscatus encodes and decodes all dates as in the format like YYYY-MM-DD
, example 1970-01-01
where:
Every string passed to and from the Piscatus API needs to be UTF-8 encoded.
National identification numbers for persons and companies are in the format YYMMDD-XXXX.
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:
Unencrypted HTTP is not supported.
Resources you have no right to see will either give you a describing status code or a 404. 404 statuses are returned if the case is such that you don’t even have the right to know, according to the systems current state, if an object exists.
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.
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.
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.
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.
Objects are mostly real-world things, such as document.
An example: /docs/1028271a4913b270df2fdaeadff09205
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
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
Utilities are defined on a per-resource basis, but their responsibilities vary from case to case.
An example: /auth
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.
The /docs
resource represents the collection of documents.
https://api.piscatus.se/v1/docs
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).
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. |
$ 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"
}
]
}
The /docs/<id>
is the object resource of documents.
https://api.piscatus.se/v1/docs/<id>
Parameter | Description |
---|---|
id | Document identifier |
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 |
$ 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"]
}
The /docs/<id>/file
resource lets you read the raw document.
https://api.piscatus.se/v1/docs/<id>/file
Parameter | Description |
---|---|
id | Document identifier |
$ 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
...
The /authorities
resource represents the collection of authorities handled by the system.
https://api.piscatus.se/v1/authorities
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 |
$ 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
},
...
]
}
The /agents
is the collection resource of agents. The actor is passed in the authorization header.
https://api.piscatus.se/v1/agents
Parameter | Description |
---|---|
count | Total numbers of agents found |
agents | List of agents |
_id | Agent identifier |
_title | Title of the agent |
$ 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"
}
]
}
The /agents<id>
is the object resource of agents. The actor is passed in the authorization header.
https://api.piscatus.se/v1/agents/<id>
Parameter | Description |
---|---|
id | Agent identifier |
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 |
$ 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"
}
The /agents/<id>/targets
is the collection resource of agent targets. The actor is passed in the authorization header.
https://api.piscatus.se/v1/agents/<id>/targets
Parameter | Description |
---|---|
id | Agent identifier |
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 |
$ 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"
}
]
}
The /agents<agent-id>/targets/<target-id>
is the object resource of targets. The actor is passed in the authorization header.
https://api.piscatus.se/v1/agents/<agent-id>/targets/<target-id>
Parameter | Description |
---|---|
agent-id | Agent identifier |
target-id | Target identifier |
Parameter | Description |
---|---|
id | Target identifier |
target | National Identification Number or freetext search query |
comment | Target comment |
$ 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"
}
The /auth
resource is the authentication and authorization endpoint. Please see the Authentication chapter for details on how to authenticate and authorize.
By default the Piscatus API returns JSON. We encourage you to use JSON.
The Piscatus API returns standard HTTP header information with all of its responses.
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 |
At some occasions the Piscatus API returns error messages. These are in JSON format.
{
"error": "access_denied"
}
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.
When accessing the Piscatus API applications must follow the same high level basic pattern which consists of four steps.
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.
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.
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.
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"
}
Piscatus accepts the application/x-www-form-urlencoded
media type for POST payload. The result is however always JSON formatted.
Piscatus supports the two major flows listed in the specification. They are explained in more detail below.
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.
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
.
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 |
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 |
$ 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"
}
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=
Parameter | Description |
---|---|
grant_type | Must be set to client_credentials |
scope | OPTIONAL, set of permissions the client requests |
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 |
$ 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"
}