NAV Navbar
shell

Introduction

Welcome to the IN COMMON API! You can use our API to access Commons resources in the IN COMMON database.

This documentation shows how to use the API with curl from the Shell. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This API documentation page was created with Slate.
The code lives in the incommon-doc repository on Framagit.
The official documentation lives at https://doc.incommon.cc/.

This documentation is a collective effort of the IN COMMON Documentors.
You are welcome to participate in the API documentation process.

High-Level Models

These models aggregate resources from the Incommon specification. They are used for reading from the IN COMMON API to retrieve ready-to-use resources (which can be collections), and create composite resources (or collections).

Model API Version Description
Agent v0 An Agent manages Resources (ActivityPub: Actor)
Event v2 An Event associates a Resource to a Moment in time
Location v0 A Location associates a Resource to a Position in space
Map v0 A map defines a collection of Resources according to a specific Classification

Agent

An agent is an Entity that manages a Resource. An agent can be an individual but, more generally, is an organization.

Example: a university, a municipality, an association, a neighborhood council... In Dewey Maps: equivalent to a resource type manager.

An agent can have one or more users who will be able to manage resources on behalf of the Agent. Agents usually match #welcome:transition-actors groups.

For API usage, see Agents.

Event

An event associates a Resource to a Moment in time. An event can be recurrent.

For API usage, see Events.

Location

A location associates a Resource to a Position in space.

For API usage, see Locations.

Map

A map defines a collection of Resources according to a specific Classification. In other words, a map provides a specific view on the Incommon database, that is sufficient to display resources on a dynamic or static map, e.g., with Leaflet.

To simply display an existing map, calling the Incommon API with the Map ID is sufficient and will return either the JSON data to feed into Leaflet, or a complete map in an <iframe> through a <script> tag. E.g., <script src="https://api.incommon.cc/v1/maps/123.js"></script>.

In Dewey Maps: equivalent to a frame.

For API usage, see Maps.

Authentication

IN COMMON uses API keys to allow access to the API. You can either use the public API key or register your own API key at our developer's site.

IN COMMON expects that each request will include an API key or secure Token.

This token SHOULD be passed as a query string parameter, e.g.:

https://api.incommon.cc/?api_key=23d8009f-f2ec-44b6-bcbe-58ad1d3af10b

Notes for v0.*

Public, Read-only Access (GET)

There's a read-only public API key you can use to request IN COMMON public resources. The key is 23d8009f-f2ec-44b6-bcbe-58ad1d3af10b.

With this key you can only retrieve public resources with a GET request.

To authorize, use this code:

require 'incommon'

api = INCOMMON::API::Client.authorize!
# With shell, you can just pass the correct header with each request
curl "$api_endpoint"
  -H "Authorization: Token 23d8009f-f2ec-44b6-bcbe-58ad1d3af10b"
const Incommon = require('incommon');

let api = Incommon.authorize();

Authenticated Access (GET, POST, PUT, DELETE)

Authenticated access is under way.

Authorization

IN COMMON API uses Pundit to manage authorization policies.

However, with the prospect of Object Capabilities, this will be revised in version 2 to move away from ACLs.

Context

The authorization context is a function of the current User and the current Agent. Each call to the API is personal (user) but all actions depend on one or more Roles of the current user in the context of the current Agent.

Given that an Agent is by design collective, different users can share a given role within a single agent's context.

Roles

Role Description
Observer Watches changes and validates against the [IN COMMON Charter]
Editor Creates and edits resources for that Agent.
Maintainer Ensures the data is correct and organizes classifications
Leader Grants roles to Agent's members

These are the 4 authorization roles, that allow answering the following questions:

Beyond these roles, others are used elsewhere within the community, which are not related to authorization of the API itself, but can affect contents all the same: Documentor, Translator, etc. have an identified role but no authorization constraints in the API. As far as the API is concerned, a User belongs to one or more Agents and within each has been assigned zero or more roles.

Unauthorized Actions

The most common case when authorization fails is to reject the request with an error. But sometimes it's better to accept the request and process it differently instead.

Errors

IN COMMON API is a JSONAPI-compliant API, therefore uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Agents

Actors in IN COMMON API are called Agents.

An agent is an Entity that manages a Resource. An agent can be an individual but, more generally, is an organization.

Example: a university, a municipality, an association, a neighborhood council… In Dewey Maps: equivalent to a resource type manager.

An agent can have one or more users who will be able to manage resources on behalf of the Agent. Agents usually match #welcome:transition-actors groups.

Classifications

IN COMMON API uses a 2-level classification for Resources. A Taxonomy is comprised of Categories and Sections.

You can retrieve a classification, including categories and sections in one call:

Get the whole classification

require 'incommon'

api = INCOMMON::API::Client.authorize!('YourAPIToken')
classification = api.taxonomies.get(taxonomy.uuid, include: [:categories, :section])
curl "https://api.incommon.cc/taxonomies?include=Category,Section"
  -H "Authorization: bearer YourJWT"
const kittn = require('kittn');

let api = kittn.authorize('meowmeowmeow');
let kittens = api.kittens.get();

The above command returns JSON structured like this:

{}

This endpoint retrieves all taxonomies.

HTTP Request

GET https://api.incommon.cc/taxonomies

Query Parameters

Parameter Default Description
include none Include Category and Section objects, when set to include=Category,Section
filter none Filter by attribute (e.g., filter=name)

Get a Specific taxonomy

require 'incommon'

uuid = Taxonomy.find_by(uuid: 'some_uuid').pluck(:uuid).first

api = INCOMMON::API::Client.authorize!('YourAPIToken')
api.taxonomies.get(uuid, include: [:categories, :sections])
curl "https://api.incommon.cc/taxonomies?include=Category,Section"
  -H "Authorization: Bearer YourJWT"
const Incommon = require('incommon');

let api = Incommon.authorize('YourAPIToken');
let classification = api.taxonomies.get(some_uuid);

The above command returns JSON structured like this:

{}

This endpoint retrieves a specific taxonomy.

HTTP Request

GET https://api.incommon.cc/taxonomies/<UUID>

URL Parameters

Parameter Description
UUID The UUID of the taxonomy to retrieve
include Optionally you can add an include query parameter to retrieve Category and Section

Collections

Collections form a group of other Resources, e.g., forming a route or a journey, a thematic grouping, or all resources on a map.

Descriptors

Descriptors are non-hierarchical classifications, available in version 1 of the API.

Type API Version Description
Event v2 An event associates a Resource with a Moment in time. An event can be recurrent
Moment v1 A time descriptor (Date, duration and recurrence)
Position v1 A spatial descriptor (GIS position, e.g., Point or Polygon)
Tag v1 A free-form textual descriptor

Commoners

The Commoners models comprise the actual API users. As mentioned in the Agents section, in ActivityPub terms, only Agents are Actors.

Model API Version Description
Agent v0 An agent is an Entity that manages a Resource
Role v0
Users v0

Agents

Roles

Users

Maps

A map defines a collection of Resources according to a specific Classification. In other words, a map provides a specific view on the INCOMMON database, that is sufficient to display resources on a dynamic or static map, e.g., with Leaflet.

To simply display an existing map, calling the INCOMMON API with the Map UUID is sufficient and will return either the JSON data to feed into Leaflet, or a complete map in an <iframe> through a <script> tag.

A map is defined by its center point (a Position, serialized as latitude and longitude), the Agent responsible for this map, a Taxonomy ordering the resources, and a Collection of resources to display.

GET a map as HTML

Status: pending

Given a map's UUID, you can simply insert this snippet of HTML in your page:

<script src="https://api.incommon.cc/maps/51895a0-6580-4b0a-9d78-8fcd896aec88.js?api_key=23d8009f-f2ec-44b6-bcbe-58ad1d3af10b"></script>

Get a map as JSON for Leaflet

Status: pending

Using the .json extension explicitely returns a serialized JSON file for direct use with Leaflet.

curl -H 'Accept: application/api+json;version=0' \
     -H 'Authorization: Token 23d8009f-f2ec-44b6-bcbe-58ad1d3af10b' \
     https://api.incommon.cc/maps/51895a0-6580-4b0a-9d78-8fcd896aec88.json

Properties

Model API Version Description
Address v0
Email v0
Link v0
Phone v0

Address

Email

Phone

Resources

Resources are the proper data objects being mapped.
IN COMMON API knows about 4 types of resources:

Model API Version Description
Entity v0 A human individual or group, e.g., an organization, an association
Place v0 A specific portion of territory in the world, e.g., a building, a bridge, a road, a forest
Service v1 A form of human support that can be given or exchanged
Thing v0 Something else, e.g., a tree, a fountain...

The Resources endpoint allows to retrieve any of such resources.
If you want to create or otherwise act upon an existing resource, you must use its specific endpoint.

Entity

Place

Service

Thing

GET a single resource

Each resource is identified with a UUID.

require 'incommon'

uuid = "some_resource_uuid"

api = INCOMMON::API::Client.authorize!(INCOMMON.api_key)
resource = api.resources.get(uuid)
curl https://api.incommon.cc/resources \
     -H 'Authorization: Token 23d8009f-f2ec-44b6-bcbe-58ad1d3af10b'
require 'incommon';

let api = Incommon.authorize()
let resource = api.resources.get(some_uuid)

GET a specific resource type

Each resource type has its own endpoint, so if you know the type, you can do:

require 'incommon'

uuid = "some_place_uuid"

api = INCOMMON::API::Client.authorize!(INCOMMON.api_key)
place = api.places.get(uuid)

GET a specific resource without UUID

You can as well search for a resource:

require 'incommon'

search = { name: 'ZAD NDDL' }

api = INCOMMON::API::Client.authorize!(INCOMMON.api_key)
place = api.places.find_by(search)