apiary.apib

FORMAT: 1A
HOST: https://helpful.io

# Helpful API

## Versioning

TODO

## Schema

TODO

## Parameters

TODO

## Client Errors

TODO

## HTTP Redirects

TODO

## HTTP Verbs

TODO

## Authentication

API authentication is done using OAuth2.  Helpful acts as an OAuth2 provider.
In order to develop an API client against Helpful, your app will need to be
registered.

More details here:

* https://github.com/applicake/doorkeeper/wiki/Authorization-Code-Flow
* http://tools.ietf.org/html/rfc6749#section-4.1

Roughly, as a Helpful user, you can:

* Create your own "applications" (OAuth clients) that can then participate in the OAuth flow.  Use the "/oauth/applications" URL.
* Authorize other applications (or your own) to "act" on your behalf (make API calls to resources you control).  Use the "/oauth/authorized_applications" URL.

Here's how to do it in development:

1. Log in as normal
2. Visit http://localhost:5000/oauth/applications
3. Create a new application (use `urn:ietf:wg:oauth:2.0:oob` as the callback URL)
4. Copy the application_id and secret key

When your app/client code wants to access Helpful as a user, it must request an auth_code.  That is done by having the user you want to act on behalf of visit the authorize_url:

```
callback = "urn:ietf:wg:oauth:2.0:oob"
app_id = "f9682933bb81c9a76cc4dc6d7b2f4ba7a1db006cc986fa5e8e28d05fafde6dd9"
secret = "23c7ebff714494e3871cf0ab163bb4e9b87bd4ad201521a3ce9e2e1ca984feda"

client = OAuth2::Client.new(app_id, secret, site: "http://localhost:3000/")

client.auth_code.authorize_url(redirect_uri: callback)
# => "http://localhost:3000/oauth/authorize?response_type=code&client_id=f9682933bb81c9a76cc4dc6d7b2f4ba7a1db006cc986fa5e8e28d05fafde6dd9&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob"
10ce24de-23f6-433f-9a71-255cffffa96
```

5. This URL will prompt the browser user if they want to allow the app and will return to you an auth_code (via callback or in the browser window).
6. Your app should remember this auth_code!
7. Then "trade-in" the auth_code for an access_token (Access tokens are short lived (2 hours).  Whenever it expires, you'll have to get a new one.

```
auth_code = "b789332903d1a6e3ec07f1831c8c4e3d20031f576e19ff2ae24dcbb26285b205"
access = client.auth_code.get_token auth_code, redirect_uri: callback
token = access.token
# => "fd7958b3d3d17ba9130718096b3a4cd4a4d8088cb29d41e4d74513fc9aeff5a8"

access.get '/api/messages'f"
# => #<OAuth2::Response:0x000000027c2778 .... (Normal HTTP Response stuff from the API call here)
```

## Hypermedia

TODO

## Pagination

TODO

## Rate Limiting

TODO

## User Agents

TODO

## Conditional Requests

TODO

## JSON-P Callbacks

TODO

# Group Accounts

These are like organizations which use Helpful.

## Accounts [/api/accounts]

### List all accounts [GET]

All the accounts the user has access to.

+ Response 200 (application/json)

        {
          "accounts": [
            {
              "id": "b3ebe711-755e-4a91-b8d2-0cc028827bcf",
              "name": "Assembly",
              "slug": "assembly",
              "website_url": "assembly.com",
              "webhook_url": "",
              "prefers_archiving": false,
              "type": "account",
              "created": "2014-04-14T10:20:23Z",
              "updated": "2014-04-14T10:20:23Z"
            }
          ]
        }

## Account [/api/accounts/{account}]

+ Parameters

    + account (required, string) ... Identifier of the account

### Retrieve an account [GET]

Get an account the user has access to.

+ Response 200 (application/json)

        {
          "account": {
            "id": "b3ebe711-755e-4a91-b8d2-0cc028827bcf",
            "name": "Assembly",
            "slug": "assembly",
            "website_url": "assembly.com",
            "webhook_url": "",
            "prefers_archiving": false,
            "type": "account",
            "created": "2014-04-14T10:20:23Z",
            "updated": "2014-04-14T10:20:23Z"
          }
        }

### Update an account [PATCH]

Update an account the user has access to.

+ Request (application/json)

        {
          "name": "Assembly Support",
          "website_url": "http://assembly.com",
          "webhook_url": "",
          "prefers_archiving": true
        }

+ Response 200 (application/json)

        {
          "account": {
            "id": "b3ebe711-755e-4a91-b8d2-0cc028827bcf",
            "name": "Assembly Support",
            "slug": "assembly",
            "website_url": "http://assembly.com",
            "webhook_url": "",
            "prefers_archiving": true,
            "type": "account",
            "created": "2014-04-14T10:20:23Z",
            "updated": "2014-04-14T10:20:23Z"
          }
        }

# Group People

People who operate or interacted with that account.

## People [/api/accounts/{account}/people]

+ Parameters

    + account (required, string) ... Identifier of the account

### List all people [GET]

List all people in an account the user has access to.

+ Response 200 (application/json)

        {
          "people": [
            {
              "id":"56f26d2f-4934-4265-b538-6e4dc2b45f91",
              "name": "Patrick",
              "email":"patrick@assembly.com",
              "type": "person",
              "created":"2014-04-14T10:20:23Z",
              "updated":"2014-04-14T10:20:23Z"
            },
            {
              "id": "8d5d6346-896a-4447-9543-74685c9adeed",
              "name": null,
              "email": "user@example.com",
              "type": "person",
              "created":"2014-04-14T11:41:05Z",
              "updated":"2014-04-14T11:41:05Z",
            }
          ]
        }

# Group Conversations

Conversations in an account.

## Conversations [/api/accounts/{account}/conversations{?archived}]

### List all the conversations [GET]

List all conversations in an account the user has access to.

+ Parameters

    + account (required, string) ... Identifier of the account
    + archived (optional, boolean) ... Archived if `true`, not if `false`

+ Response 200 (application/json)

        {
          "conversations": [
            {
              "id": "73156f8e-a90a-42ea-bfca-cbd80eb39",
              "subject": null,
              "tags": [],
              "number": 1,
              "type": "conversation",
              "created": "2014-04-14T11:41:05Z",
              "updated": "2014-04-14T11:41:23Z"
            }
          ]
        }

### Create a conversation [POST]

Create a conversation in an account the user has access to.

+ Parameters

    + account (required, string) ... Identifier of the account

+ Request

        {
          "subject": "Another help thread"
        }

+ Response 201 (application/json)

        {
          "conversation": {
            "id": "412158ca-e9d5-465b-b013-2bddc5b17d47",
            "messages": [],
            "subject": "Another help thread",
            "tags": [],
            "number": 3,
            "type": "conversation",
            "created": "2014-04-14T15:43:33Z",
            "updated": "2014-04-14T15:43:33Z"
          }
        }

## Conversation [/api/conversations/{conversation}]

+ Parameters

    + conversation (required, string) ... Identifier of the conversation

### Retrieve a conversation [GET]

Get a conversation the user has access to.

+ Response 200 (application/json)

        {
          "conversation": {
            "id": "459598d5-522b-4b97-8f5a-fab3ea6cb",
            "subject": null,
            "tags": [],
            "messages": [
              {
                "id": "33314e4e-baf5-4b33-be72-112ed86701fd",
                "body": "How do you do?",
                "body_html": null,
                "conversation_id": "459598d5-522b-4b97-8f5a-fab3ea6cb",
                "person_id": "c690ca56-a0af-40df-9389-75264635154a",
                "type": "message",
                "created": "2014-04-14T11:43:00Z",
                "updated": "2014-04-14T11:43:00Z"
              }
            ],
            "number": 2,
            "type": "conversation",
            "created": "2014-04-14T11:43:00Z",
            "updated": "2014-04-14T15:03:21Z"
          }
        }

# Group Messages

Messages in conversations the user has access to.

## Messages [/api/conversations/{conversation}/messages]

+ Parameters

    + conversation (required, string) ... Identifier of the conversation

### List all messages [GET]

List all messages in a conversation the user has access to.

+ Response 200 (application/json)

        {
          "messages": [
            {
              "id": "bdc4daf1-8070-42d1-bfee-4cfef7ffb95b",
              "body": "I need help please.",
              "body_html": null,
              "conversation_id": "73156f8e-a90a-42ea-bfca-cbd80eb39",
              "person_id": "8d5d6346-896a-4447-9543-74685c9adeed",
              "type": "message",
              "created": "2014-04-14T11:41:05Z",
              "updated": "2014-04-14T11:41:05Z"
            },
            {
              "id": "33314e4e-baf5-4b33-be72-112ed86701fd",
              "body": "What did you need?",
              "body_html": null,
              "conversation_id": "73156f8e-a90a-42ea-bfca-cbd80eb39",
              "person_id": "c690ca56-a0af-40df-9389-75264635154a",
              "type": "message",
              "created": "2014-04-14T11:43:00Z",
              "updated": "2014-04-14T11:43:00Z"
            }
          ]
        }

### Create a message [POST]

Create a new message in a conversation the user has access to.

+ Request (application/json)

        {
          "conversation": "459598d5-522b-4b97-8f5a-fab3ea6cb",
          "person": "56f26d2f-4934-4265-b538-6e4dc2b45f91",
          "body": "Fine, I am good"
        }

+ Response 201 (application/json)

        {
          "message": {
            "id": "eb41dec1-9eb6-4ec8-a286-7d3def86889d",
            "body": "Fine, I am good",
            "body_html": null,
            "conversation_id": "459598d5-522b-4b97-8f5a-fab3ea6cb",
            "person_id": "56f26d2f-4934-4265-b538-6e4dc2b45f91",
            "type": "message",
            "created": "2014-04-14T16:35:15Z",
            "updated": "2014-04-14T16:35:15Z"
          }
        }

## Message [/api/messages/{message}]

### Retrieve a message [GET]

Get a message the user has access to.

+ Parameters

    + message (required, string) ... Identifier of the message

+ Response 200 (application/json)

        {
          "message": {
            "id": "33314e4e-baf5-4b33-be72-112ed86701fd",
            "body": "How do you do?",
            "body_html": null,
            "conversation_id": "459598d5-522b-4b97-8f5a-fab3ea6cb",
            "person_id": "c690ca56-a0af-40df-9389-75264635154a",
            "type": "message",
            "created": "2014-04-14T11:43:00Z",
            "updated": "2014-04-14T11:43:00Z"
          }
        }

# Group Attachments

Attachments of messages the user has access to.

## Attachments [/api/messages/{message}/attachments]

### List all attachments [GET]

List all the attachments of a message the user has access to.

+ Parameters

    + message (required, string) ... Identifier of the message

+ Response 200 (application/json)

        {
          "attachments": [
            {

            }
          ]
        }

## Attachment [/api/attachments/{attachment}]

### Retrieve an attachment [GET]

Get an attachment the user has acess to.

+ Parameters

    + attachment (required, string) ... Identifier of the attachment

+ Response 200 (application/json)

        {
          "attachment": {

          }
        }