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