API

This is the specification of the public API.

Status codes are generally:

  • 200: ok
  • 400: something wrong with the request
  • 401: authentication error
  • 404: not found
  • 500: server or database error

If an endpoint has parameters they are required for the request to success (otherwise a 400 is thrown). A parameter not found in the URL should be sent in the request body as application/x-www-form-urlencoded. Some endpoints require input as JSON. The endpoint description will include a special JSON Request object if JSON is required.

Project

A project specifies the default taxonomy which collections can extend. Usually each project is hosted on a different website.

{
   "name": "serp",
   "link": "http://serpconnect.cs.lth.se"
}

Where name is a unique (across backends) project name and link a url to the website of the project.

Query projects

GET /v1/project

Get a list of all known projects.

Example response:

{
    "projects": [PROJECT]
}
Response JSON Object:
 
  • projects (array) – An array of Project objects.
Status Codes:
  • 200 OK – ok, return taxonomy

Create new project

POST /v1/project

Create a new project listing.

Parameters:
  • name (string) – unique, alphanumeric name ([a-zA-Z0-9])
  • link (string) – url to website of the project
Response Headers:
 

Example response:

{
    "name": "serp-test",
    "link": "http://test.serpconnect.cs.lth.se"
}
Response JSON Object:
 
  • name (string) – the name you provided
  • link (string) – the link you provided
Status Codes:

Query project taxonomy

GET /v1/project/(string: name)/taxonomy

Get a flattened version of the project taxonomy. The flattened graph assumes an implicit “ROOT” node object as the top parent.

Parameters:
  • name (String) – unique, alphanumeric project name
 
{
    "version": 0,
    "taxonomy": [FACETS]
}
Response JSON Object:
 
  • version (integer) – A version identifier.
  • taxonomy (array) – An array of Facet objects. The flattened taxonomy.
Status Codes:

Update project taxonomy

PUT /v1/project/(string: name)/taxonomy

Update the extended taxonomy. The request will only pass if the version is >= (greater than or equal to) the currently stored version.

Parameters:
  • name (string) – project name
 
{
   "version": 0,
   "taxonomy": [FACETS]
}
Request JSON Object:
 
  • version (integer) – Reference to the version this extension is based on.
  • taxonomy (array) – The Facet nodes of the extended taxonomy.
Status Codes:

Graph

A graph consists of entries and edges.

GET /v1/entry

Fetch all entries and edges in the database.

{
      "nodes": [ENTRIES],
      "edges": [EDGES]
}
Response JSON Object:
 
  • nodes (array) – An array of Entry objects
  • edges (array) – An array of Edge objects
Status Codes:

Graph Taxonomy

GET /v1/entry/taxonomy

Get a flattened version of the standard SERP taxonomy. The flattened graph assumes an implicit “ROOT” node object as the top parent.

{
    "version": 0,
    "taxonomy": [FACETS]
}
Response JSON Object:
 
  • version (integer) – A version identifier.
  • taxonomy (array) – An array of Facet objects. The flattened taxonomy.
Status Codes:
  • 200 OK – ok, return taxonomy

Facet

A node in the taxonomy tree is called a facet.

{
   "id": "PLANNING",
   "name": "Test planning",
   "parent": "SCOPE"
}

Where id is a (per-taxonomy) unique identifier of this facet, name is a descriptive name and parent is the id of the parent node (since a taxonomy is a tree).

Edge

An edge looks like this:

{
    "source": 9,
    "target": 13,
    "type": "PLANNING"
}

Where source is the origin entry node id, target is the targeted entity node id and type the (SERP) classification of this relation.

Entry

An entry is either a classified challenge or research result that a user submitted to the database. Each entry consists of entry-specific information and a classification. These two pieces of data must be queried separately. See Find entry by id and Get entry taxonomy.

Find entry by id

GET /v1/entry/(int: entry_id)

Retrieve information of an entry specified by entry_id.

Parameters:
  • entry_id (int) – entry’s unique id
Response Headers:
  
{
    "id": 55,
    "hash": "YOnPVli1utklw1a3LXiw9pBl6gmpsd4BUabV9I1UyhA=",
    "type": "research",
    "contact": "space_monkey@planet.zoo",
    "reference": "An In-Depth study of the Space Monkey Phenomenon",
    "doi": "doi:xyz",
    "description": null,
    "date": null,
    "pending": false
}
Response JSON Object:
 
  • id (integer) – a (recycled) unique id
  • hash (string) – unique hash of this information
  • type (string) – challenge or research
  • contact (string) – not used
  • reference (string) – only valid for research type entries, lists relevant references
  • doi (string) – only valid for research type entries, optional, the DOI of a related paper
  • date (string) – currently broken, a standard javascript date
  • pending (boolean) – is entry pending admin approval
Status Codes:
  • 200 OK – ok, return information
  • 400 Bad Request – entry_id must be an int
  • 404 Not Found – no entry with that id exists at the moment (it might have existed but was deleted)

Get entry taxonomy

GET /v1/entry/(int: entry_id)/taxonomy

Retrieve the taxonomy of a specific entry.

Parameters:
  • entry_id (int) – entry’s unique id
Response Headers:
  
{
    "INFORMATION": [
        "No data currently collected"
    ],
    "SOLVING": [
        "unspecified"
    ],
    "PLANNING": [
        "testing environment trade-off (simulated, real system production)",
        "testing phase trade-off",
        "testing-level trade-off (function, interaction)",
        "automation trade-off"
    ]
}
Response JSON Object:
 
  • <key> (array) – each key corresponds to a classification with entities
Status Codes:
  • 200 OK – ok, return entry taxonomy
  • 400 Bad Request – entry_id must be an int
  • 404 Not Found – no entry with that id exists at the moment (it might have existed but was deleted)

Submit new entry

POST /v1/entry/new

Submit a new entry.

Request JSON Object:
 
  • entryType (string) – either challenge or research
  • collection (int) – unique id of collection to add entry to
  • reference (string) – only required for research entries, a list of references
  • doi (string) – optional for research entries, a DOI of this publication
  • description (string) – only required for challenge entries, describing the challenge
  • serpClassification (json) – the SERP classification
  • date (string) – javascript date text representation

Example request json:

{
    "entryType": "challenge",
    "collection": 2,
    "description": "how to do software dev without cookies?",
    "date": "Mon Sep 28 1998 14:36:22 GMT-0700 (PDT)",
    "serpClassification": {
        "IMPROVING": ["cookies for software dev"],
        "INFORMATION": ["hungry hungry devs"]
    }
}

Example response:

{
    "message": "ok"
}
Status Codes:

Edit existing entry

PUT /v1/entry/(int: entry_id)

Edit taxonomy and/or fields of an existing entry. Request is same as Submit new entry, but without a collection field.

param entry_id:unique id of entry
type entry_id:int

Example request:

{
    entryType: "challenge",
    description: "how to do software dev without cookies?",
    date: "Mon Sep 28 1998 14:36:22 GMT-0700 (PDT)",
    serpClassification: {
        "IMPROVING": ["cookies for software dev"],
        "INFORMATION": ["hungry hungry devs"]
    }
}
Status Codes:

Account

Authenticate

POST /v1/account/login

Authenticate user.

Status Codes:
  • 200 OK – ok, user is logged in on the returned session token
  • 400 Bad Request – email/passw combination is invalid

Register an account

POST /v1/account/register

Register new user.

Status Codes:

Reset password

The password reset process is simple:

  • User clicks ‘reset my password’ and enters email
  • Email is sent to the email address (1)
  • User clicks on link in received email
  • Backend checks token in url, sets session flag and forwards to frontend
  • User enters new password and submits new password
  • User is now logged in and the old password has been replaced
POST /v1/account/reset-password

Send a password reset request. Matches (1) in the description above.

Status Codes:
GET /v1/account/reset-password?(string: token)

Consume the reset token and return a new, flagged, session id. Forwards to frontend.

Parameters:
  • token (string) – a querystring value of the reset token found in the email
Status Codes:

Only requests with an attached session id that is considered authenticated (i.e. after Authenticate) are allowed access to routes below.

Check login status

GET /v1/account/login

Test if session is authenticated/user is logged in.

Status Codes:

Get friends of a user

GET /v1/account/friends
Parameters:
  • email (String) – entry’s unique email
 
["turtle@rock.gov", "zebra@afri.ca"]
Response JSON Object:
 
  • emails (array) – an array of emails related to the users email including the users email.

Get collections

GET /v1/account/collections

Query a list of collections that the currently authenticated user is a member of.

Parameters:
  • project (String) – include only collections in this project
Response Headers:
  
[ { "name": "rick's best systems", "id": 2 } ]
Response JSON Array of Objects:
 
  • name – non-unique name of the collection
  • id – unique id of the collection

Query self

GET /v1/account/self

Get an at-a-glance snapshot of stats and data about the current user.

Response Headers:
  
{
   "email": "zoo@world.gov",
   "trust": "Admin",
   "collections": [COLLECTIONS]
   "entries": [ENTRIES]
}
Response JSON Object:
 
  • email (string) – user’s email
  • trust (string) – trust level (see Trust)
  • collections (array) – An array of collection objects, equivalent to Get collections
  • entries (array) – An array of approved/pending Entry objects this user has submitted.

Logout

POST /v1/account/logout

Logout this user and reset the session.

Status Codes:

Delete account

POST /v1/account/delete

WARNING - Delete the currently authenticated user.

Change password

POST /v1/account/change-password

Change authentication password. Does not require subsequent requests to re-authenticate.

Request JSON Object:
 
  • old (string) – old password
  • new (string) – new password
Status Codes:

Get collection invites

GET /v1/account/invites

Query list of collections have user is invited to. Return equivalent to Get collections.

Query user by email

GET /v1/account/(string: email)

Perform Query self but target a specific user. Returns same output.

Parameters:
  • email (string) – email of user
Status Codes:

Collection

Create new collection

POST /v1/collection/

Create a new collection.

Parameters:
  • name (string) – the collection’s name (doesn’t have to be unique).
Status Codes:

Get collection graph

GET /v1/collection/(int: id)/graph

Query the node graph of entries and entities.

Parameters:
  • id (int) – collection id
 
{
   "nodes": [ENTRIES],
   "edges": [EDGES]
}
Response JSON Object:
 
  • nodes (array) – An array of Entry objects.
  • edges (array) – An array of Edge objects.
Status Codes:

Get statistics

GET /v1/collection/(int: id)/stats

Query number of members and entries in this collection.

Parameters:
  • id (int) – collection id
 
{
    "members": 2,
    "entries": 9
}
Response JSON Object:
 
  • members (int) – number of users, excluding invited, that connected to this collection
  • entries (int) – number of entries that are connected to this collection
Status Codes:

Get collection project

GET /v1/collection/(int: id)/project

Query the project this collection extends.

Parameters:
  • id (int) – collection id
 
{
   "name": "serp",
   "link": "http://serpconnect.cs.lth.se"
}
Status Codes:

Get entries

GET /v1/collection/(int: id)/entries

Query entries in this collection.

Parameters:
  • id (int) – collection id
 
[Entry, Entry, ..., Entry]
Response JSON Array of Objects:
 
  • Entry – An Entry object.
Status Codes:

Only requests with an attached session id, where the user is directly connected to the specified collection, are allowed access to these routes.

Accept an invite

POST /v1/collection/(int: id)/accept

Accept an invitation to join a specific collection.

Parameters:
  • id (int) – collection id
Status Codes:
  • 400 Bad Request – must provide id, id must be an integer, must be invited to that exception
  • 404 Not Found – no collection with that id exists

Only requests with an attached session id, where the user is directly connected to the specified collection, are allowed access to these routes.

Send an invite

POST /v1/collection/(int: id)/invite

Invite a user to a collection.

Parameters:
  • id (int) – collection id
Request JSON Object:
 
  • name (string) – name of the collection
Status Codes:

Leave a collection

POST /v1/collection/(int: id)/leave

Leave the collection.

Parameters:
  • id (int) – collection id
Status Codes:

Remove an entry

POST /v1/collection/(int: id)/removeEntry

Remove an entry from the collection. If the entry isn’t included in any other collections it is removed.

Parameters:
  • id (int) – collection id
Request JSON Object:
 
  • entryId (int) – id of entry to remove
Status Codes:

Add an existing entry

POST /v1/collection/(int: id)/addEntry

Add an existing entry to the collection. This will copy the specified entry. The classifications where the facet exists in both taxonomies are copied.

Parameters:
  • id (int) – collection id
Request JSON Object:
 
  • entryId (int) – id of entry to add
Status Codes:

Get members of a collection

GET /v1/collection/(int: id)/members

Query members in this collection.

Parameters:
  • id (int) – collection id
 
[User, ..., User]
Response JSON Array of Objects:
 
Status Codes:

Get the extended taxonomy

GET /v1/collection/(int: id)/taxonomy

Query the extended taxonomy of this collection. Facet objects returned by this query will reference the standard serp taxonomy, which must be queried separately.

Parameters:
  • id (int) – collection id
 
{
   "version": 0,
   "taxonomy": [FACETS]
}
Response JSON Object:
 
  • version (integer) – Version identifier. Important for updating the taxonomy.
  • taxonomy (array) – The Facet nodes of the extended taxonomy.
Status Codes:

Update the extended taxonomy

PUT /v1/collection/(int: id)/taxonomy

Update the extended taxonomy. The request will only pass if the version is >= (greater than or equal to) the currently stored version.

Parameters:
  • id (int) – collection id
 
{
   "version": 0,
   "taxonomy": [FACETS]
}
Request JSON Object:
 
  • version (integer) – Reference to the version this extension is based on.
  • taxonomy (array) – The Facet nodes of the extended taxonomy.
Status Codes:

Reclassify some entities

POST /v1/collection/(int: id)/reclassify

Replace old facets with new facets for some entities.

Parameters:
  • id (int) – collection id
 
{
   "oldFacetId": "PEOPLE",
   "newFacetId": "STRANGE-PEOPLE",
   "entities": [213, 255]
}
Request JSON Object:
 
  • oldFacetId (string) – The facet id that is to be replaced.
  • newFacetId (string) – The replacement facet id.
  • entity (array) – ids of the entities that are to be reclassified.
Status Codes:

Get all the entities

GET /v1/collection/(int: id)/entities

Get all the entities.

Parameters:
  • id (int) – collection id
 
[
   {
      "id": 222,
      "text": "Regression testing"
   }
]
Response JSON Array of Objects:
 
  • id – id of the entity
  • text – user text of the entity
Status Codes:

Query the classification

GET /v1/collection/(int: id)/classification

Get all the entities grouped by taxonomy facet.

Parameters:
  • id (int) – collection id
 
[
   {
      "facetId": "PEOPLE",
      "text": ["Shifty chimpanzees", "Rectangular red birds"]
   }
]
Response JSON Array of Objects:
 
  • facetId – id of the Facet
  • text – text of the entities classified with this facet
Status Codes:

Admin

Only requests with an attached session id, where user’s trust level is Admin, are allowed access to these routes.

GET /v1/admin

Check if current user (via session token) is an admin.

Status Codes:
GET /v1/admin/pending

Get all pending entries.

[Entry, Entry, ..., Entry]
Response JSON Array of Objects:
 
  • Entry – An Entry object.
Status Codes:
GET /v1/admin/collections

Get all collections that the admin is NOT member of

[Collection, Collection, ..., Collection]
Response JSON Array of Objects:
 
Status Codes:
POST /v1/admin/delete-collection

Delete a collection

Parameters:
  • entry (int) – ID of collection to delete.
Status Codes:
GET /v1/admin/collections-owned-by

Return names of all collections user is owner of

Parameters:
  • email – email of the user
Status Codes:
POST /v1/admin/accept-entry

Accept a pending entry.

Parameters:
  • entry (int) – ID of entry to accept.
Status Codes:
POST /v1/admin/reject-entry

Reject a pending entry.

Parameters:
  • entry (int) – ID of entry to reject.
Status Codes:
POST /v1/admin/delete-user

Delete a user with a given email

Parameters:
  • email – email of the user to be deleted
Status Codes:
POST /v1/admin/delete-entry

Delete entry with a given entry id

Parameters:
  • entryId – id of the entry
Status Codes:
PUT /v1/admin/set-trust

Set trust level of a specific user.

Parameters:
  • email (string) – Email of user affected user.
  • trust (string) – New trust level (Admin, Verified, User, Registered, Unregistered).
Status Codes:
GET /v1/admin/users

Get all users.

[User, User, ..., User]
Response JSON Array of Objects:
 
Status Codes:
GET v1/admin/is-collection-owner
param id:id of the collection
type id:int

Return true if the admin is owner of the collection

Status Codes: