DRAFT API

Draft exposes its data through a REST API using JSON serialization and protected with OAuth 2. For testing or personal use, you can use basic authentication with your Draft email and password. But for using the API with other users, please use OAuth 2.

Requests

Requests to Draft are required to be over SSL and start with: 

https://draftin.com/api/v1/

Here's how you can make test requests using curl: 

curl -u email:password \
  https://draftin.com/api/v1/documents.json

If you're sending data to Draft, make sure you include a Content-Type header of application/json. For example: 

curl -u email:password \
  -X POST -H "Content-Type: application/json" -d '{"content":"xyz"}' \
  https://draftin.com/api/v1/documents.json

Pagination

Some API endpoints require pagination, for example: Documents. For these, please use a "page" parameter (first page starting at 1) to fetch multiple pages of records.

Endpoints

OAuth 2

Please fill out this form and tell me a little bit about what you want to do with Draft's API. I'll get you setup with the credentials you need for OAuth.

Here's a sample application in Ruby to show you how to use OAuth to authenticate with Draft and issue some basic API calls.

Documents

Fields describing a document: 

{   
    "id": The id of this document,
    "name": "The Name of your Document",
    "content": "The plain-text markdown of your document",
    "content_html": "Your document rendered as HTML",
    "user": {
        id: 1, 
        email: 'usersemail@example.com'
    },
    "created_at": "2013-05-23T14:11:54-05:00",
    "updated_at": "2013-05-23T14:11:58-05:00"
    "parent_id": 123
    "token": A secret token for sharing a document
}

If a document has a parent_id, then this document is a fork of another document.

Get Documents

GET /documents.json

Will return all documents for this user. They are sorted by most recently updated and use pagination.

Example: 

curl -u email:password \
  https://draftin.com/api/v1/documents.json

Get a Single Document

GET documents/:id.json

Example: 

curl -u email:password \
  https://draftin.com/api/v1/documents/1.json

Create a Document

POST documents.json

Post the content and an optional name for your document. 

{   
    "name": "An optional name of the Document",
    "content": "The plain-text markdown of your document"
}

Example: 

curl -u email:password \
  -X POST -H "Content-Type: application/json" -d '{"content":"xyz"}' \
  https://draftin.com/api/v1/documents.json

Update a Document

PUT documents/:id.json

Post the content and an optional name for your document. 

{   
    "name": "An optional name of the Document",
    "content": "The plain-text markdown of your document"
}

Example: 

curl -u email:password \
  -X PUT -H "Content-Type: application/json" -d '{"content":"hi"}' \
  https://draftin.com/api/v1/documents/894.json

Delete a Document

DELETE documents/:id.json

Example: 

curl -u email:password \
  -X DELETE \
  https://draftin.com/api/v1/documents/894.json

Compare a document with a collaborator

GET /documents/:id/compare.json?fork_id=:fork_id

Will return an array of changes similar to the standard GNU diff/patch format. Each change in this array can either be merged or ignored.

[
    "@@ -8,16 +8,17 @@\n  a thing\n+!\n %0D%0A%0D%0ADraf\n",
    "@@ -27,21 +27,16 @@\n exposes \n-it's \n+\n data thr\n",
    "@@ -192,16 +192,46 @@\n password\n+. You should also mention this\n .%0D%0A%0D%0AI l\n",
    "@@ -243,12 +243,24 @@\n ou and this.\n+%0D%0A%0D%0AGo away.\n"
]

Example: 

curl -u email:password \
  https://draftin.com/api/v1/documents/924/compare.json?fork_id=927

Merge a change from a collaborator

POST /documents/:id/merge.json

When you have an array of changes, you can use the index of this change (starting at 0) to merge that change into the parent document.

[
    "@@ -8,16 +8,17 @@\n  a thing\n+!\n %0D%0A%0D%0ADraf\n",
    "@@ -27,21 +27,16 @@\n exposes \n-it's \n+\n data thr\n",
    "@@ -192,16 +192,46 @@\n password\n+. You should also mention this\n .%0D%0A%0D%0AI l\n",
    "@@ -243,12 +243,24 @@\n ou and this.\n+%0D%0A%0D%0AGo away.\n"
]

Example: 

curl -u email:password \
  -X POST -H "Content-Type: application/json" -d '{"fork_id":927, "index":3}' \
  https://draftin.com/api/v1/documents/924/merge.json

Create a sharing token

POST documents/:id/share.json

By default when a document is created it doesn't have a secret sharing token. Use this API call to generate a token. This will return a document JSON object with its token populated.

Example: 

curl -u email:password \
  -X POST -d ''\
  https://draftin.com/api/v1/documents/928/share.json

Forks

Forks are collaborators' versions of a document. A fork is just another document that has a parent_id.

Fields describing a fork: 

{   
    "id": id,
    "name": "The Name of your Document",
    "content": "The plain-text markdown of your document",
    "content_html": "Your document rendered as HTML",
    "user": {
        id: 1, 
        email: 'usersemail@example.com'
    },
    "created_at": "2013-05-23T14:11:54-05:00",
    "updated_at": "2013-05-23T14:11:58-05:00"
    "parent_id": 123
}

Create a Fork

POST /documents/:id/forks.json

If you want to collaborate on a document, you need to create a fork for this user. An individual user can only create a single fork to the same document. To create a fork, you need to use the secret token of the parent document. 

curl -u email:password \
  -X POST -H "Content-Type: application/json" -d '{"token": "h__lRztowftHDAk-bPWNhgZov41oMduxQnfhzOQEFI"}' \
https://draftin.com/api/v1/documents/905/forks.json

Returns the JSON representing the new document created.

Get Forks

GET /documents/:id/forks.json

Get all the collaborators of a document.

Example: 

curl -u email:password \
  https://draftin.com/api/v1/documents/905/forks.json

Complete a Fork

POST /forks/:id/complete.json

Completing a fork lets the owner of the document know that this user's version is complete and can be reviewed for merging into their document. A completion can include an optional note argument letting the original document's author know more context of the changes. 

{   
    "note": "Looked great. Just Made a couple changes."
}

Example: 

curl -u email:password \
  -X POST -H "Content-Type: application/json" -d '{}' \
  https://draftin.com/api/v1/forks/906/complete.json

People

Fields describing a person:

{
    "body_background_color": The custom background color being used.,
    "body_font_family": "source-code-pro",
    "body_font_size": "1.125em",
    "body_text_color": "#333",
    "created_at": "2012-04-03T17:13:26-05:00",
    "email": "nate@cityposh.com",
    "first_name": "Nate",
    "id": 5,
    "last_name": "Kontny",
    "time_zone": "Central Time (US & Canada)",
    "updated_at": "2013-05-30T16:14:14-05:00"
}

Get the Current Logged in User

GET people/me.json

Example: 

curl -u email:password \
  https://draftin.com/api/v1/people/me.json

Savepoints

A savepoint is a manually saved version of a document's content by the same owner.

Fields describing a savepoint: 

{
    "content": "Some content",
    "created_at": "2013-05-30T17:11:51-05:00",
    "document_id": 861,
    "id": 733,
    "name": The name of the savepoint.,
    "updated_at": "2013-05-30T17:11:51-05:00"
}

Get Savepoints

GET documents/:id/savepoints.json

Will return all savepoints for this document. They are sorted by most recently created.

Example: 

curl -u email:password \
  https://draftin.com/api/v1/documents/861/savepoints.json

Get a Single Savepoint

GET savepoints/:id.json

Will return a single savepoint.

Example: 

curl -u email:password \
  https://draftin.com/api/v1/savepoints/123.json

Create a Savepoint

POST documents/:id/savepoints.json

Will save the most current version of this document as a savepoint.

Example: 

curl -u email:password \
  -X POST  -d '' \
  https://draftin.com/api/v1/documents/861/savepoints.json

Delete a Savepoint

DELETE savepoints/:id.json

Example: 

curl -u email:password \
  -X DELETE \
  https://draftin.com/api/v1/savepoints/734.json

API under development

Tell me what you need from the API so I can prioritize what gets worked on next.

-Nate

@natekontny http://ninjasandrobots.com