TERESAH API documentation

TODO: Extend and clean up the API documentation.

TODO: Update the API request and response examples.

Introduction

TERESAH provides a RESTful application programming interface (API) where each type of resource has a URI that you can interact with. API follows the principles of a RESTful web service wherever possible. It uses versioning to allow backwards-incompatible modifications in the service without affecting clients using older versions of the API.

This technical document is intended for developers building applications using the TERESAH API. Basic knowledge in programming is required to use the API. The API is independent from any programming language.

Schema, request and response data formats

All API access is over HTTP(S), and by default accessed from the teresah.dariah.eu domain.

All data is sent and received in UTF-8 character encoding as JavaScript Object Notation (JSON) format. The Content-Type header must always be specified. Generally the application/json; charset=utf-8 content-type is supported. Please note, that setting the Content-Type header is purposely omitted in the API documentation examples.

All timestamps are returned in the ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).

Authentication

All API requests are required to be authenticated with an API key and identified with a User-Agent header. Please note, that setting the X-Auth-Token and User-Agent headers are purposely omitted in the API documentation examples. You can request your private API key from the "Manage API Keys" page.

Identify your integration

You must include a User-Agent header with the name of your integration and a link to it (or your email address instead of link) so we can get in touch if needed. If you don't supply this header, you will receive a 400 Bad Request. Here are few valid examples on how to identify your integration.

$ curl -H "X-Auth-Token: API_KEY" -A "TERESAH (http://teresah.dariah.eu/)" http://teresah.dariah.eu/api/v1/users.json

Authenticating using an API key

API requests using an API key require an X-Auth-Token header. If you don't supply this header, you will receive a 401 Unauthorized. Here's an example of using an API key to query available users:

$ curl -H "X-Auth-Token: API_KEY" http://teresah.dariah.eu/api/v1/users.json

Rate limiting

The TERESAH API only allows clients to make a limited number of requests per hour. You can perform up to 600 request per hour from the same IP address. If you exceed this limit, you'll get a 429 Too Many Requests response for subsequent requests. It is considered best practice for applications to monitor their current rate limit status and dynamically throttle requests if necessary. All response headers include your current rate limit status in X-RateLimit-Limit and X-RateLimit-Remaining header.

Available API endpoints

TERESAH provides the following API endpoints to interact with.

  • Activities
  • Data Sources
  • Data Types
  • Logins
  • Tools & Tool data
  • Users

Activities

Get activities

GET /api/v1/activities.json(?limit=20) will return all activities you can request information about. Available activity event types (actions) are 1 = Created, 2 = Updated, 3 = Deleted, 4 = Restored. See documentation of "Get a single activity" for details on how to query for a specific activity.

Parameters

Name Type Description
limit integer The number of activities to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/activities.json?limit=3

Response

{
  "status": {
    "code": 200
  },
  "activities": {
    "total": 6223,
    "per_page": 3,
    "current_page": 1,
    "last_page": 2075,
    "from": 1,
    "to": 3,
    "data": [
      {
        "id": 12431,
        "target_type": "User",
        "target_id": 4,
        "action": 2,
        "user_id": 4,
        "metadata": "{\"name\":\"Dwight Schrute\"}",
        "ip_address": "127.0.0.1",
        "user_agent": "curl/7.35.0",
        "referer": null,
        "created_at": "2014-12-10T15:30:58+00:00",
        "updated_at": "2014-12-10T15:30:58+00:00",
        "user": {
          "id": 4,
          "name": "Dwight Schrute",
          "locale": "en",
          "created_at": "2014-11-26T10:19:57+00:00",
          "updated_at": "2014-12-10T15:30:58+00:00",
          "deleted_at": null
        }
      },
      ...
    ]
  }
}

Get an activity

GET /api/v1/activities/{id}.json will return specific activity you can request information about.

Request

$ curl http://teresah.dariah.eu/api/v1/activities/12407.json

Response

{
  "status": {
    "code": 200
  },
  "id": 12407,
  "target_type": "Signup",
  "target_id": 4,
  "action": 1,
  "user_id": 4,
  "metadata": "{\"name\":\"Dwight Schrute\"}",
  "ip_address": "10.0.2.2",
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.65 Safari/537.36",
  "referer": "http://teresah.dariah.eu/signup",
  "created_at": "2014-11-26T10:19:58+00:00",
  "updated_at": "2014-11-26T10:19:58+00:00",
  "user": {
    "id": 4,
    "name": "Dwight Schrute",
    "locale": "en",
    "created_at": "2014-11-26T10:19:57+00:00",
    "updated_at": "2014-12-10T15:30:58+00:00",
    "deleted_at": null
  }
}

Data Sources

Get data sources

GET /api/v1/data-sources.json(?limit=20) will return all available data sources you can request information about. See documentation of "Get an data source" for details on how to query for a specific data source.

Parameters

Name Type Description
limit integer The number of data sources to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/data-sources.json

Response

{
  "status": {
    "code": 200
  },
  "data_sources": {
    "total": 4,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 4,
    "data": [
      {
        "id": 5,
        "name": "TERESAH",
        "slug": "teresah",
        "description": "TERESAH (Tools E-Registry for E-Social science, Arts and Humanities) is a cross-community tools knowledge registry aimed at researchers in the Social Sciences and Humanities (SSH). It aims to provide an authoritative listing of the software tools currently in use in those domains, and to allow their users to make transparent the methods and applications behind them.",
        "homepage": "http://teresah.dariah.eu/",
        "user_id": 3,
        "created_at": "2014-11-25T09:24:32+00:00",
        "updated_at": "2014-11-25T09:24:32+00:00",
        "deleted_at": null,
        "user": {
          "id": 3,
          "name": "TERESAH",
          "locale": "en",
          "created_at": "2014-11-25T09:24:31+00:00",
          "updated_at": "2014-11-25T09:24:31+00:00",
          "deleted_at": null
        }
      },
      ...
    ]
  }
}

Get an data source

GET /api/v1/data-sources/{id}.json will return specific available data source you can request information about.

Request

$ curl http://teresah.dariah.eu/api/v1/data-sources/5.json

Response

{
  "status": {
    "code": 200
  },
  "id": 5,
  "name": "TERESAH",
  "slug": "teresah",
  "description": "TERESAH (Tools E-Registry for E-Social science, Arts and Humanities) is a cross-community tools knowledge registry aimed at researchers in the Social Sciences and Humanities (SSH). It aims to provide an authoritative listing of the software tools currently in use in those domains, and to allow their users to make transparent the methods and applications behind them.",
  "homepage": "http://teresah.dariah.eu/",
  "user_id": 3,
  "created_at": "2014-11-25T09:24:32+00:00",
  "updated_at": "2014-11-25T09:24:32+00:00",
  "user": {
    "id": 3,
    "name": "TERESAH",
    "locale": "en",
    "created_at": "2014-11-25T09:24:31+00:00",
    "updated_at": "2014-11-25T09:24:31+00:00",
    "deleted_at": null
  }
}

Create an data source

POST /api/v1/data-sources.json will create a new data source.

Parameters

Name Type Description
name string Required The unique name for the data source.
slug string The slug for the data source (automatically generated from the name).
description string The description of the data source.
homepage string The homepage of the data source.
user_id integer Required The identifier for the user (automatically filled from the authentication).

Request

$ curl -X POST --data-binary @payload.json http://teresah.dariah.eu/api/v1/data-sources.json
{
  "name": "TERESAH",
  "description": "TERESAH (Tools E-Registry for E-Social science, Arts and Humanities) is a cross-community tools knowledge registry aimed at researchers in the Social Sciences and Humanities (SSH). It aims to provide an authoritative listing of the software tools currently in use in those domains, and to allow their users to make transparent the methods and applications behind them.",
  "homepage": "http://teresah.dariah.eu/"
}

Response

{
  "status": {
    "code": 201,
    "message": "Data Source was successfully registered."
  }
}

Update the data source

PUT/PATCH /api/v1/data-sources/{id}.json will update the specific data source from the parameters passed.

Request

$ curl -X PATCH --data-binary @payload.json http://teresah.dariah.eu/api/v1/data-sources/5.json
{
  "name": "Wikipedia",
  "description": "Wikipedia is a free-access, free content Internet encyclopedia, supported and hosted by the non-profit Wikimedia Foundation."
}

Response

{
  "status": {
    "code": 200,
    "message": "Data Source was successfully updated."
  }
}

Delete data source

DELETE /api/v1/data-sources/{id}.json will delete the specific data source and return 200 OK if that was successful. If you don't not have access to delete the data source, you'll receive a 403 Forbidden.

Request

$ curl -X DELETE http://teresah.dariah.eu/api/v1/data-sources/5.json

Response

{
  "status": {
    "code": 200,
    "message": "Data Source was successfully deleted."
  }
}

Data Types

Get data types

GET /api/v1/data-types.json(?limit=20) will return all available data types you can request information about. See documentation of "Get an data type" for details on how to query for a specific data type.

Parameters

Name Type Description
limit integer The number of data types to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/data-types.json

Response

{
  "status": {
    "code": 200
  },
  "data_types": {
    "total": 8,
    "per_page": 5,
    "current_page": 1,
    "last_page": 2,
    "from": 1,
    "to": 5,
    "data": [
      {
        "id": 10,
        "label": "Description",
        "slug": "description",
        "description": "General description of the tool",
        "rdf_mapping": "http://purl.org/dc/elements/1.1/description",
        "linkable": 0,
        "user_id": 3,
        "created_at": "2014-11-25T09:24:32+00:00",
        "updated_at": "2014-11-25T09:24:32+00:00",
        "deleted_at": null,
        "user": {
          "id": 3,
          "name": "TERESAH",
          "locale": "en",
          "created_at": "2014-11-25T09:24:31+00:00",
          "updated_at": "2014-11-25T09:24:31+00:00",
          "deleted_at": null
        }
      },
      ...
    ]
  }
}

Get an data type

GET /api/v1/data-types/{id}.json will return specific available data type you can request information about.

Request

$ curl http://teresah.dariah.eu/api/v1/data-types/5.json

Response

{
  "status": {
    "code": 200
  },
  "id": 12,
  "label": "Developer",
  "slug": "developer",
  "description": "Organization or person who developed the tool",
  "rdf_mapping": "http://purl.org/dc/elements/1.1/creator",
  "linkable": 1,
  "user_id": 3,
  "created_at": "2014-11-25T09:24:32+00:00",
  "updated_at": "2014-11-25T09:24:32+00:00",
  "user": {
    "id": 3,
    "name": "TERESAH",
    "locale": "en",
    "created_at": "2014-11-25T09:24:31+00:00",
    "updated_at": "2014-11-25T09:24:31+00:00",
    "deleted_at": null
  }
}

Create an data type

POST /api/v1/data-types.json will create a new data type.

Parameters

Name Type Description
user_id integer Required The identifier for the user (automatically filled from the authentication).
label string Required The unique label/name for the data type.
slug string The slug for the data type (automatically generated from the label).
description string The description of the data type.
rdf_mapping string RDF mapping of the data type.
linkable boolean Data type is linkable?

Request

$ curl -X POST --data-binary @payload.json http://teresah.dariah.eu/api/v1/data-types.json
{
  "label": "description",
  "description": "General description of the tool",
  "rdf_mapping": "http://purl.org/dc/elements/1.1/description",
  "linkable": false
}

Response

{
  "status": {
    "code": 201,
    "message": "Data Type was successfully registered."
  }
}

Update the data type

PUT/PATCH /api/v1/data-types/{id}.json will update the specific data type from the parameters passed.

Request

$ curl -X PATCH --data-binary @payload.json http://teresah.dariah.eu/api/v1/data-types/18.json
{
  "label": "platform",
  "description": "Platform the tool runs on"
}

Response

{
  "status": {
    "code": 200,
    "message": "Data Type was successfully updated."
  }
}

Delete data type

DELETE /api/v1/data-types/{id}.json will delete the specific data type and return 200 OK if that was successful. If you don't not have access to delete the data type, you'll receive a 403 Forbidden.

Request

$ curl -X DELETE http://teresah.dariah.eu/api/v1/data-types/15.json

Response

{
  "status": {
    "code": 200,
    "message": "Data Type was successfully deleted."
  }
}

Harvesters

Get harvesters

GET /api/v1/harvesters.json(?limit=20) will return all harvesters you can request information about. See documentation of "Get a harvester" for details on how to query for a specific harvester record.

Parameters

Name Type Description
limit integer The number of harvesters to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/harvesters.json?limit=1

Response

{
  "status": {
    "code": 200
  },
  "harvesters": {
    "total": 1,
    "per_page": 2,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 1,
    "data": [
      {
        "id": 1,
        "data_source_id": 89,
        "label": "TERESAH-HARVESTER-TEST",
        "slug": "teresah-harvester-test",
        "url": "https://teresah.dariah.eu/harvester_page.html",
        "active": 1,
        "launch_now": 0,
        "last_launched": "2017-10-19 09:35:02",
        "user_id": 22,
        "created_at": "2017-10-19T07:37:38+00:00",
        "updated_at": "2017-10-19T09:35:02+00:00",
        "user": {
          "id": 22,
          "name": "Yoann Supervisor",
          "locale": "en",
          "password_reset_sent_at": null,
          "created_at": "2017-10-19T08:52:33+00:00",
          "updated_at": "2017-10-19T09:38:31+00:00",
          "deleted_at": null
        },
        "data_source": {
          "id": 89,
          "name": "TERESAH-HARVESTER-DATASOURCE",
          "slug": "teresah-harvester-datasource",
          "description": "The TERESAH harvester data source is used for testing the harvester implementation of TERESAH",
          "homepage": "http://teresah.dariah.eu",
          "user_id": 21,
          "created_at": "2017-10-19T07:37:09+00:00",
          "updated_at": "2017-10-19T07:37:09+00:00",
          "deleted_at": null,
          "user": {
            "id": 21,
            "name": "TERESAH Admin",
            "locale": "en",
            "created_at": "2017-10-10T09:24:31+00:00",
            "updated_at": "2017-10-10T09:24:31+00:00",
            "deleted_at": null
          }
        }
      }
    ]
  }
}

Get a harvester record

GET /api/v1/harvesters/{id}.json will return specific harvester record you can request information about.

Request

$ curl http://teresah.dariah.eu/api/v1/harvesters/1.json

Response

{
  "status": {
    "code": 200
  },
  "id": 1,
  "data_source_id": 89,
  "label": "TERESAH-HARVESTER-TEST",
  "slug": "teresah-harvester-test",
  "url": "https://teresah.dariah.eu/harvester_page.html",
  "active": 1,
  "launch_now": 0,
  "last_launched": "2017-10-19 09:35:02",
  "user_id": 22,
  "created_at": "2017-10-19T07:37:38+00:00",
  "updated_at": "2017-10-19T09:35:02+00:00",
  "user": {
    "id": 22,
    "name": "Yoann Supervisor",
    "locale": "en",
    "password_reset_sent_at": null,
    "created_at": "2017-10-19T08:52:33+00:00",
    "updated_at": "2017-10-19T09:38:31+00:00",
    "deleted_at": null
  },
  "data_source": {
    "id": 89,
    "name": "TERESAH-HARVESTER-DATASOURCE",
    "slug": "teresah-harvester-datasource",
    "description": "The TERESAH harvester data source is used for testing the harvester implementation of TERESAH",
    "homepage": "http://teresah.dariah.eu",
    "user_id": 21,
    "created_at": "2017-10-19T07:37:09+00:00",
    "updated_at": "2017-10-19T07:37:09+00:00",
    "deleted_at": null,
    "user": {
      "id": 21,
      "name": "TERESAH Admin",
      "locale": "en",
      "created_at": "2017-10-10T09:24:31+00:00",
      "updated_at": "2017-10-10T09:24:31+00:00",
      "deleted_at": null
    }
  }
}

Logins

Get logins

GET /api/v1/logins.json(?limit=20) will return all logins you can request information about. See documentation of "Get a login" for details on how to query for a specific login record.

Parameters

Name Type Description
limit integer The number of logins to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/logins.json?limit=3

Response

{
  "status": {
    "code": 200
  },
  "logins": {
    "total": 8,
    "per_page": 3,
    "current_page": 1,
    "last_page": 3,
    "from": 1,
    "to": 3,
    "data": [
      {
        "id": 8,
        "user_id": 4,
        "ip_address": "10.0.2.2",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36",
        "referer": "http://teresah.dariah.eu/login",
        "via_remember": 0,
        "created_at": "2014-12-05T11:00:25+00:00",
        "updated_at": "2014-12-05T11:00:25+00:00",
        "deleted_at": null,
        "user": {
          "id": 4,
          "name": "Dwight Schrute",
          "locale": "en",
          "created_at": "2014-11-26T10:19:57+00:00",
          "updated_at": "2014-12-10T15:30:58+00:00",
          "deleted_at": null
        }
      },
      ...
    ]
  }
}

Get a login record

GET /api/v1/logins/{id}.json will return specific login record you can request information about.

Request

$ curl http://teresah.dariah.eu/api/v1/logins/7.json

Response

{
  "status": {
    "code": 200
  },
  "id": 7,
  "user_id": 4,
  "ip_address": "10.0.2.2",
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36",
  "referer": "http://teresah.dariah.eu/login",
  "created_at": "2014-12-05T09:24:26+00:00",
  "updated_at": "2014-12-05T09:24:26+00:00",
  "user": {
    "id": 4,
    "name": "Dwight Schrute",
    "locale": "en",
    "created_at": "2014-11-26T10:19:57+00:00",
    "updated_at": "2014-12-10T15:30:58+00:00",
    "deleted_at": null
  }
}

Tools

Get tools

GET /api/v1/tools.json(?limit=20) will return all available tools you can request information about. See documentation of "Get a tool" for details on how to query for a specific tool.

Parameters

Name Type Description
limit integer The number of tools to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/tools.json?limit=2

Response

{
  "status": {
    "code": 200
  },
  "tools": {
    "total": 676,
    "per_page": 3,
    "current_page": 1,
    "last_page": 226,
    "from": 1,
    "to": 3,
    "data": [
      {
        "id": 1280,
        "name": "TypePad",
        "slug": "typepad",
        "user_id": 3,
        "created_at": "2014-11-25T09:24:37+00:00",
        "updated_at": "2014-11-25T09:24:37+00:00",
        "deleted_at": null,
        "user": {
          "id": 3,
          "name": "TERESAH",
          "locale": "en",
          "created_at": "2014-11-25T09:24:31+00:00",
          "updated_at": "2014-11-25T09:24:31+00:00",
          "deleted_at": null
        },
        "data_sources": [
          {
            "id": 5,
            "name": "TERESAH",
            "slug": "teresah",
            "description": "TERESAH (Tools E-Registry for E-Social science, Arts and Humanities) is a cross-community tools knowledge registry aimed at researchers in the Social Sciences and Humanities (SSH). It aims to provide an authoritative listing of the software tools currently in use in those domains, and to allow their users to make transparent the methods and applications behind them.",
            "homepage": "http://teresah.dariah.eu/",
            "user_id": 3,
            "created_at": "2014-11-25T09:24:32+00:00",
            "updated_at": "2014-11-25T09:24:32+00:00",
            "deleted_at": null,
            "pivot": {
              "tool_id": 1280,
              "data_source_id": 5,
              "created_at": "2014-11-25 09:24:39",
              "updated_at": "2014-11-25 09:24:39"
            }
          },
          ...
        ]
      },
      ...
    ]
  }
}

Search tools

GET /api/v1/tools/search.json?q={keyword}(?limit=20) will return all available tools you can request information about that match your search criteria.

Parameters

Name Type Description
q string The search keyword. TERESAH tries to match tool name with the provided keyword.
limit integer The number of tools to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/tools/search.json?q=ruby&limit=10

Response

{
  "status": {
    "code": 200
  },
  "tools": {
    "total": 2,
    "per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 2,
    "data": [
      {
        "id": 1134,
        "name": "Ruby on Rails",
        "slug": "ruby-on-rails",
        "user_id": 3,
        "created_at": "2014-11-25T09:24:36+00:00",
        "updated_at": "2014-11-25T09:24:36+00:00",
        "deleted_at": null,
        "user": {
          "id": 3,
          "name": "TERESAH",
          "locale": "en",
          "password_reset_sent_at": null,
          "created_at": "2014-11-25T09:24:31+00:00",
          "updated_at": "2014-11-25T09:24:31+00:00",
          "deleted_at": null
        },
        "data_sources": [
          {
            "id": 5,
            "name": "TERESAH",
            "slug": "teresah",
            "description": "TERESAH (Tools E-Registry for E-Social science, Arts and Humanities) is a cross-community tools knowledge registry aimed at researchers in the Social Sciences and Humanities (SSH). It aims to provide an authoritative listing of the software tools currently in use in those domains, and to allow their users to make transparent the methods and applications behind them.",
            "homepage": "http://teresah.dariah.eu/",
            "user_id": 3,
            "created_at": "2014-11-25T09:24:32+00:00",
            "updated_at": "2014-11-25T09:24:32+00:00",
            "deleted_at": null,
            "pivot": {
              "tool_id": 1134,
              "data_source_id": 5,
              "created_at": "2014-11-25 09:24:38",
              "updated_at": "2014-11-25 09:24:38"
            }
          },
          ...
        ]
      },
      ...
    ]
  }
}

Get a tool

GET /api/v1/tools/{id}.json will return specific available tool you can request information about.

Request

$ curl http://teresah.dariah.eu/api/v1/tools/1280.json

Response

{
  "status": {
    "code": 200
  },
  "id": 1280,
  "name": "TypePad",
  "slug": "typepad",
  "user_id": 3,
  "created_at": "2014-11-25T09:24:37+00:00",
  "updated_at": "2014-11-25T09:24:37+00:00",
  "user": {
    "id": 3,
    "name": "TERESAH",
    "locale": "en",
    "created_at": "2014-11-25T09:24:31+00:00",
    "updated_at": "2014-11-25T09:24:31+00:00",
    "deleted_at": null
  },
  "data_sources": [
    {
      "id": 5,
      "name": "TERESAH",
      "slug": "teresah",
      "description": "TERESAH (Tools E-Registry for E-Social science, Arts and Humanities) is a cross-community tools knowledge registry aimed at researchers in the Social Sciences and Humanities (SSH). It aims to provide an authoritative listing of the software tools currently in use in those domains, and to allow their users to make transparent the methods and applications behind them.",
      "homepage": "http://teresah.dariah.eu/",
      "user_id": 3,
      "created_at": "2014-11-25T09:24:32+00:00",
      "updated_at": "2014-11-25T09:24:32+00:00",
      "deleted_at": null,
      "pivot": {
        "tool_id": 1280,
        "data_source_id": 5,
        "created_at": "2014-11-25 09:24:39",
        "updated_at": "2014-11-25 09:24:39"
      },
      "data": [
        {
          "id": 10372,
          "data_source_id": 5,
          "tool_id": 1280,
          "user_id": 4,
          "data_type_id": 13,
          "value": "blog",
          "slug": "blog",
          "created_at": "2014-11-25T09:25:23+00:00",
          "updated_at": "2014-12-03T14:08:54+00:00",
          "deleted_at": null,
          "user": {
            "id": 4,
            "name": "Dwight Schrute",
            "locale": "en",
            "created_at": "2014-11-26T10:19:57+00:00",
            "updated_at": "2014-12-10T15:30:58+00:00",
            "deleted_at": null
          },
          "data_type": {
            "id": 13,
            "label": "Keyword",
            "slug": "keyword",
            "description": "Free form keywords describing the tool",
            "rdf_mapping": "http://purl.org/dc/elements/1.1/subject",
            "linkable": 1,
            "user_id": 3,
            "created_at": "2014-11-25T09:24:32+00:00",
            "updated_at": "2014-11-25T09:24:32+00:00",
            "deleted_at": null
          }
        },
        ...
      ]
    },
    ...
  ]
}

Create a tool

POST /api/v1/tools.json will create a new tool.

Parameters

Name Type Description
name string Required The unique name for the tool.
slug string The slug for the tool (automatically generated from the name).
user_id integer Required The identifier for the user (automatically filled from the authentication).

Request

$ curl -X POST --data-binary @payload.json http://teresah.dariah.eu/api/v1/tools.json
{
  "name": "Ruby on Rails"
}

Response

{
  "status": {
    "code": 201,
    "message": "Tool was successfully created."
  }
}

Update the tool

PUT/PATCH /api/v1/tools/{id}.json will update the specific tool from the parameters passed.

Request

$ curl -X PATCH --data-binary @payload.json http://teresah.dariah.eu/api/v1/tools/1371.json
{
  "name": "Laravel Framework"
}

Response

{
  "status": {
    "code": 200,
    "message": "Tool was successfully updated."
  }
}

Delete tool

DELETE /api/v1/tools/{id}.json will delete the specific tool and return 200 OK if that was successful. If you don't not have access to delete the tool, you'll receive a 403 Forbidden.

Request

$ curl -X DELETE http://teresah.dariah.eu/api/v1/tools/37.json

Response

{
  "status": {
    "code": 200,
    "message": "Tool was successfully deleted."
  }
}

Attach data source to tool

POST /api/v1/tools/{tool_id}/data-sources.json will attach data source to specified tool from the parameters passed.

Parameters

Name Type Description
tool_id integer Required The identifier for the tool.
data_source_id integer Required The identifier for the data source.

Request

$ curl -X POST --data-binary @payload.json http://teresah.dariah.eu/api/v1/tools/1371/data-sources.json
{
  "data_source_id": 3
}

Response

{
  "status": {
    "code": 201,
    "message": "Data Source was successfully attached to Tool."
  }
}

Detach data source from tool

DELETE /api/v1/tools/{tool_id}/data-sources/{data_source_id}.json will detach data source from the specified tool from the parameters passed.

Parameters

Name Type Description
tool_id integer Required The identifier for the tool.
data_source_id integer Required The identifier for the data source.

Request

$ curl -X DELETE http://teresah.dariah.eu/api/v1/tools/1371/data-sources/3.json

Response

{
  "status": {
    "code": 200,
    "message": "Data Source was successfully detached from Tool."
  }
}

Add tool data to data source

POST /api/v1/tools/{tool_id}/data-sources/{data_source_id}/data.json will create a new data entry for the specified tool, under the specified data source.

Parameters

Name Type Description
tool_id integer Required The identifier for the tool.
data_source_id integer Required The identifier for the data source.
data_type_id integer Required The identifier for the data type.
user_id integer Required The identifier for the user (automatically filled from the authentication).
value string Required The content for the data entry.
slug string The slug for the data entry (automatically generated from the value).

Request

$ curl -X POST --data-binary @payload.json http://teresah.dariah.eu/api/v1/tools/1371/data-sources/5/data.json
{
  "data_type_id": 2,
  "value": "Ruby on Rails, or simply Rails, is an open source web application framework written in Ruby."
}

Response

{
  "status": {
    "code": 201,
    "message": "Data entry was successfully created for the Data Source."
  }
}

Update tool data in data source

PUT/PATCH /api/v1/tools/{tool_id}/data-sources/{data_source_id}/data/{id}.json will update the specific tool data from the parameters passed.

Request

$ curl -X PATCH --data-binary @payload.json http://teresah.dariah.eu/api/v1/tools/1371/data-sources/5/data/11011.json
{
  "data_type_id": 1,
  "value": "Ruby on Rails"
}

Response

{
  "status": {
    "code": 200,
    "message": "Data entry was successfully updated for the Data Source."
  }
}

Delete tool data from the data source

DELETE /api/v1/tools/{tool_id}/data-sources/{data_source_id}/data/{id}.json will delete the specific tool data and return 200 OK if that was successful. If you don't not have access to delete the tool data, you'll receive a 403 Forbidden.

Request

$ curl -X DELETE http://teresah.dariah.eu/api/v1/tools/1371/data-sources/5/data/11011.json

Response

{
  "status": {
    "code": 200,
    "message": "Data entry was successfully deleted from the Data Source."
  }
}

Users

Available user levels

TERESAH supports four (4) different user levels. User level dictates how user can interact with TERESAH.

  • Authenticated user: User with registered account. Can edit own profile and create lists of tools.
  • Collaborator: Authenticated user with collaborator status. Can add and edit tools and data types.
  • Supervisor: Authenticated user with supervisor status. Can add, edit and remove tools, data types, data sources, list activities, and harvest other data sources.
  • Administrator: Authenticated user with administrator status. Has full access to all administrative functions.

Get users

GET /api/v1/users.json(?limit=20) will return all available users you can request information about. See documentation of "Get a user" for details on how to query for a specific user.

Parameters

Name Type Description
limit integer The number of users to list per page/response.
page integer Return the specific page from the paginated result set.

Request

$ curl http://teresah.dariah.eu/api/v1/users.json?limit=2

Response

{
  "users": {
    "total": 2,
    "per_page": 3,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 2,
    "data": [
      {
        "id": 6,
        "email_address": "teresah@example.org",
        "name": "TERESAH",
        "locale": "en",
        "created_at": "2014-09-23T07:20:26+00:00",
        "updated_at": "2014-09-23T07:20:26+00:00",
        "deleted_at": null,
        "logins": []
      },
      {
        "id": 7,
        "email_address": "dwight.schrute@dundermifflin.com",
        "name": "Dwight Schrute",
        "locale": "en",
        "created_at": "2014-09-23T07:27:34+00:00",
        "updated_at": "2014-09-24T07:29:58+00:00",
        "deleted_at": null,
        "logins": [
          {
            "id": 1,
            "user_id": 7,
            "ip_address": "10.0.2.2",
            "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36",
            "referer": "http://teresah.dariah.eu/login",
            "via_remember": 0,
            "created_at": "2014-09-24T07:29:59+00:00",
            "updated_at": "2014-09-24T07:29:59+00:00",
            "deleted_at": null
          }
        ]
      }
    ]
  }
}

Get a user

GET /api/v1/users/{id}.json will return specific available user you can request information about.

Request

$ curl http://teresah.dariah.eu/api/v1/users/37.json

Response

{
  "status": {
    "code": 200
  },
  "id": 37,
  "name": "Dwight Schrute",
  "locale": "en",
  "created_at": "2014-11-26T10:19:57+00:00",
  "updated_at": "2014-12-05T10:12:50+00:00",
  "logins": [
    {
      "id": 1,
      "user_id": 37,
      "ip_address": "10.0.2.2",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.65 Safari/537.36",
      "referer": "http://teresah.dariah.eu/login",
      "via_remember": 0,
      "created_at": "2014-11-26T10:23:23+00:00",
      "updated_at": "2014-11-26T10:23:23+00:00",
      "deleted_at": null
    }
  ]
}

Create a user account

POST /api/v1/users.json will create a new user account. Please note, that signing up via the social media is available via the user interface only.

Parameters

Name Type Description
email_address string Required The email address for the user.
password string Required The password for the user. Password should be at least 8 characters long.
password_confirmation string Required The password confirmation should match submitted password.
name string Required The name for the user.
locale string Required The locale for the user (available locales are en and sv).
active boolean Required Is the user account activated by default?
user_level integer Required The user level for the user. Available levels are: 1 = authenticated user, 2 = collaborator, 3 = supervisor, 4 = administrator.

Request

$ curl -X POST --data-binary @payload.json http://teresah.dariah.eu/api/v1/users.json
{
  "email_address": "dwight.schrute@dundermifflin.com",
  "password": "password",
  "password_confirmation": "password",
  "name": "Dwight Schrute",
  "locale": "en",
  "active": true,
  "user_level": 1
}

Response

{
  "status": {
    "code": 201,
    "message": "User Account was successfully created."
  }
}

Update the user account

PUT/PATCH /api/v1/users/{id}.json will update the specific user account from the parameters passed.

Request

$ curl -X PATCH --data-binary @payload.json http://teresah.dariah.eu/api/v1/users/37.json
{
  "email_address": "dwight@dundermifflin.com",
  "name": "Dwight Schrute",
  "user_level": 3
}

Response

{
  "status": {
    "code": 200,
    "message": "User Account was successfully updated."
  }
}

Delete user account

DELETE /api/v1/users/{id}.json will delete the specific user account and return 200 OK if that was successful. If you don't not have access to delete the user account, you'll receive a 403 Forbidden.

Request

$ curl -X DELETE http://teresah.dariah.eu/api/v1/users/37.json

Response

{
  "status": {
    "code": 200,
    "message": "User Account was successfully deleted."
  }
}