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": {
}
}