transientBug API Documentation

v1 API

Introduction

The v1 API tries to conform to JSON-API v1.0 format.

Exceptions:

Additionally, this document is generated from acceptance tests using JSON Schemas so it should always be up to date with the current API.

Issues

Issues with the API should be reported on Github. Please check to make sure that the issue you are reporting does not already have an issue created, as to help my sanity when managing them.

Authentication

The transientBug v1 API uses HTTPS and provides several methods of authentication, depending on the use case: Third Party Clients and Personal Tools.

Third Party Client OAuth2

Third Party Clients are defined as mass distributed clients, such as native applications, browser extensions and web apps. For these clients, OAuth2 Authorization Code Grant flow is provided.

Developers can register new OAuth2 applications here, for now you’ll need a minumum of a name and redirect url and will be provided a CLIENT_ID and CLIENT_SECRET which you will use below.

To obtain an access token, first make a GET request to /oauth/authorize:

/oauth/authorize?client_id=CLIENT_ID
  &redirect_uri=REDIRECT_URL
  &response_type=code

where CLIENT_ID is the client ID provided when registering the application, and REDIRECT_URL is the same redirect url you used when registering the application.

On a successful call, this will redirect to the REDIRECT_URL with a code in the query string. With that code, issue a POST to /oauth/token:

/oauth/token?client_id=CLIENT_ID
  &client_secret=CLIENT_SECRET
  &code=RETURNED_CODE
  &grant_type=authorization_code
  &redirect_uri=REDIRECT_URL

where CLIENT_SECRET is the value provided after registering your app, and RETURNED_CODE is the code from the first requests redirect. A successful request will return a JSON payload with an access_token key.

After this, you can begin using the API, with all requests containing the access_token in an Authorization Bearer header: Authorization: Bearer <access_token>

Personal Tools

For Personal Tools, small scale applications and other utilities developed for personal use, two simple methods are provided, modeled off of the Pinboard v1 API with the intention of trying to be easy to use and develop against:

  • HTTP Basic Auth: https://<email>:<password>@transientbug.ninja/api/v1/<method>
  • Query String API Tokens: https://transientbug.ninja/api/v1/<method>?auth_token=<email>:<auth_token>

The query string API token can also be sent along in the JSON body for POST, PATCH and PUT requests.

You are encouraged to only use Basic Auth to grab the API token through the profile endpoint, and should prefer to use the API token method everywhere to avoid storing your password.

You can find your API token on your profile page. Through this page you can also regenerate your token, however this will invalidate your previous API token.

Changes

July, 2019

As of late July, 2019 the Bookmarks create endpoint no longer overwrites existing bookmark data and will now respond with a 302 to the found bookmark.

v1 Bookmarks

Check for a non-existent bookmark

Endpoint

GET /api/v1/bookmarks/check

Parameters

Name Description
auth_token Required Authentication Token
url Required URL to check

Request

Route

GET /api/v1/bookmarks/check?auth_token=person5%40example.com%3Aa96b02e53c92595f4f033e48cd26553dc0a1350e472727560f2269d7f2f304fe&url=http%3A%2F%2Fnot.found

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Query Parameters

auth_token=person5@example.com:a96b02e53c92595f4f033e48cd26553dc0a1350e472727560f2269d7f2f304fe
url=http://not.found

Response

Status

404

Headers

Content-Type: application/vnd.api+json

Check for an existing bookmark

Endpoint

GET /api/v1/bookmarks/check

Parameters

Name Description
auth_token Required Authentication Token
url Required URL to check

Request

Route

GET /api/v1/bookmarks/check?auth_token=person4%40example.com%3Ab798f12f49a0f87116e8d4e85a9e04b4f6ab286377a5cb1cc27a96a44d3b06ca&url=http%3A%2F%2F4.example.com

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Query Parameters

auth_token=person4@example.com:b798f12f49a0f87116e8d4e85a9e04b4f6ab286377a5cb1cc27a96a44d3b06ca
url=http://4.example.com

Response

Status

302

Headers

Content-Type: application/vnd.api+json

Check with no URL

Endpoint

GET /api/v1/bookmarks/check

Parameters

Name Description
auth_token Required Authentication Token

Request

Route

GET /api/v1/bookmarks/check?auth_token=person6%40example.com%3A9765d2dd962f451ce69a37a171d891604950e1c00cb7dcb39fae4a1dd5523234

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Query Parameters

auth_token=person6@example.com:9765d2dd962f451ce69a37a171d891604950e1c00cb7dcb39fae4a1dd5523234

Response

Status

400

Headers

Content-Type: application/vnd.api+json

Delete a bookmark

Endpoint

DELETE /api/v1/bookmarks/:id

Parameters

Name Description
auth_token Required Authentication Token
id Required Bookmark ID

Request

Route

DELETE /api/v1/bookmarks/2

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Query Parameters

auth_token=person2@example.com:30bd79b12293d549687d17a8ea5ea994162b67abcb3c0975ec1e0430eec1b026

Response

Status

204

Headers

Get All Bookmarks

Endpoint

GET /api/v1/bookmarks

Parameters

Name Description
auth_token Required Authentication Token

Request

Route

GET /api/v1/bookmarks?auth_token=person3%40example.com%3A29bef9a43960a81d631e98daa7efd7ccfdebb987aac634483aad5b8028baa3ec

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Query Parameters

auth_token=person3@example.com:29bef9a43960a81d631e98daa7efd7ccfdebb987aac634483aad5b8028baa3ec

Response

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": [
    {
      "type": "bookmark",
      "id": 3,
      "attributes": {
        "title": "test",
        "description": null,
        "created_at": "2019-08-07T15:56:19.591Z",
        "updated_at": "2019-08-07T15:56:19.591Z",
        "uri": "http://3.example.com",
        "url": "http://3.example.com",
        "tags": [
          "tag5",
          "tag6"
        ]
      },
      "links": {
        "self": "http://example.org/api/v1/bookmarks/3",
        "view": "http://example.org/bookmarks/3"
      }
    }
  ],
  "links": {
    "self": "http://example.org/api/v1/bookmarks?page=1",
    "first": "http://example.org/api/v1/bookmarks?page=1",
    "prev": null,
    "next": null,
    "last": "http://example.org/api/v1/bookmarks?page=1"
  },
  "meta": {
    "count": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

Get a Bookmark

Endpoint

GET /api/v1/bookmarks/:id

Parameters

Name Description
auth_token Required Authentication Token
id Required Bookmark ID

Request

Route

GET /api/v1/bookmarks/6?auth_token=person8%40example.com%3Ad0f5505ee798dcdd741632800f3e201d45dbefd70f8926dc48186c66ad3aa334

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Query Parameters

auth_token=person8@example.com:d0f5505ee798dcdd741632800f3e201d45dbefd70f8926dc48186c66ad3aa334

Response

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "type": "bookmark",
    "id": 6,
    "attributes": {
      "title": "test",
      "description": null,
      "created_at": "2019-08-07T15:56:20.812Z",
      "updated_at": "2019-08-07T15:56:20.812Z",
      "uri": "http://5.example.com",
      "url": "http://5.example.com",
      "tags": [
        "tag9",
        "tag10"
      ]
    },
    "links": {
      "self": "http://example.org/api/v1/bookmarks/6",
      "view": "http://example.org/bookmarks/6"
    }
  }
}

Update a Bookmark

Endpoint

PATCH /api/v1/bookmarks/:id

Parameters

Name Description
auth_token Required Authentication Token
id Required Bookmark ID
data.type Required bookmark
data.id Required Bookmark ID to update
data.attributes.url Required Bookmarks URL
data.attributes.title Required Title
data.attributes.description Description/Note
data.attributes.tags Comma separated

Request

Route

PATCH /api/v1/bookmarks/1

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Body

{
  "auth_token": "person1@example.com:ae8fe47f2a13e210a86dfb3894de4a715a959ab02e6777d0b1af443645ff91dc",
  "data": {
    "type": "bookmark",
    "id": 1,
    "attributes": {
      "url": "https://bookmark.example",
      "title": "bookmark 1",
      "description": "Something witty",
      "tags": [
        "tag 1",
        "tag 2",
        "tag 3"
      ]
    }
  }
}

Response

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "type": "bookmark",
    "id": 1,
    "attributes": {
      "title": "bookmark 1",
      "description": "Something witty",
      "created_at": "2019-08-07T15:56:17.535Z",
      "updated_at": "2019-08-07T15:56:18.729Z",
      "uri": "http://1.example.com",
      "url": "http://1.example.com",
      "tags": [
        "tag 1",
        "tag 2",
        "tag 3"
      ]
    },
    "links": {
      "self": "http://example.org/api/v1/bookmarks/1",
      "view": "http://example.org/bookmarks/1"
    }
  }
}

Upsert a Bookmark

Endpoint

POST /api/v1/bookmarks

Parameters

Name Description
auth_token Required Authentication Token
data.type Required bookmark
data.attributes.url Required Bookmarks URL
data.attributes.title Required Title
data.attributes.description Description/Note
data.attributes.tags Comma separated

Request

Route

POST /api/v1/bookmarks

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Body

{
  "auth_token": "person7@example.com:7f3bc0bd3277ef197b76d88a5205e391a76bcb511e9c08dbc9e3b17ca767cf80",
  "data": {
    "type": "bookmark",
    "attributes": {
      "url": "https://bookmark.example",
      "title": "bookmark 1",
      "description": "Something witty",
      "tags": [
        "tag 1",
        "tag 2",
        "tag 3"
      ]
    }
  }
}

Response

Status

201

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "type": "bookmark",
    "id": 5,
    "attributes": {
      "title": "bookmark 1",
      "description": "Something witty",
      "created_at": "2019-08-07T15:56:20.551Z",
      "updated_at": "2019-08-07T15:56:20.551Z",
      "uri": "https://bookmark.example",
      "url": "https://bookmark.example",
      "tags": [
        "tag 1",
        "tag 2",
        "tag 3"
      ]
    },
    "links": {
      "self": "http://example.org/api/v1/bookmarks/5",
      "view": "http://example.org/bookmarks/5"
    }
  }
}

v1 Profile

Get

Fetch the users profile information, including their api_token and email used to build the auth_token.

Endpoint

GET /api/v1/profile

Parameters

Name Description
auth_token Required Authentication Token

Request

Route

GET /api/v1/profile?auth_token=person9%40example.com%3Aef18296f156848e9aed929f53a8ee90ea4807ee178296469ba9080b9c6e2001e

Headers

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

Query Parameters

auth_token=person9@example.com:ef18296f156848e9aed929f53a8ee90ea4807ee178296469ba9080b9c6e2001e

Response

Status

200

Headers

Content-Type: application/vnd.api+json

Body

{
  "data": {
    "type": "profile",
    "id": 9,
    "attributes": {
      "api_token": "ef18296f156848e9aed929f53a8ee90ea4807ee178296469ba9080b9c6e2001e",
      "username": "person9",
      "email": "person9@example.com"
    },
    "links": {
      "self": "http://example.org/api/v1/profile"
    }
  }
}