Draft of DataHub's REST API. https://github.com/datahuborg/datahub

datahub_rest_api.md

##Endpoints

All endpoints are prepended with /api/v1

USERS

method	path	accepts	return keys	description
GET	/user	-	{"username", "last_login", "email"}	current user's info
GET	/user/repos	-	{"repos": [{"owner", "colaborators":[], "permissions", "repo_name"]}	repositories owned by the current user
GET	/repos	-	see above	repositories visible to the current user

REPOS

method	path	accepts	return keys	description
GET	/repos/:user	-	see above	repositories owned by the specified user
POST	/repos/:user	{'repo'}	see above	create a repo owned by the specified user
DELETE	/repos/:user/:repo	_	-	delete a repo owned by the specified user
PATCH	/repos/:user/:repo	_	see above	rename a repo owned by the specified user

COLLABORATORS

method	path	accepts	return keys	description
GET	/repos/:user/:repo /collaborators	_	[{'username', 'permissions'}]	list all collaborators of a repo owned by the specified user. Permissions are a database -specific string
POST	/repos/:user/:repo /collaborators/:collaborator	{'permissions'}	see above
DELETE	/repos/:user/:repo /collaborators/:collaborator	_	see above	remove a collaborator from the repo owned by the specified user

TABLES

method	path	accepts	return keys	description
GET	/repos/:user/:repo /tables	-	[]	list all tables in a repo
GET	/repos/:user/:repo /tables/:table	-	[{'column_name', 'data_type'}]	view a table's info
POST	/repos/:user/:repo /tables	{'table_name', 'params'}		create a new table
DELETE	/repos/:user/:repo /tables/:table	-	-	delete a table
POST	/repos/:user/:repo /files?from_table=:tablename	{'table_name', 'file_name'}		export a table to a file

VIEWS

method	path	accepts	return keys	description
GET	/repos/:user/:repo /views	-	[]	list all views in a repo
GET	/repos/:user/:repo /views/:view	-	[{'column_name', 'data_type'}]	view a view's info
POST	/repos/:user/:repo /views	{sql'}	[]	create a new view
DELETE	/repos/:user/:repo /views/:view	-	-	delete a view
POST	/repos/:user/:repo /files?from_view=:view	{'view_name', 'file_name'}		export a view to a file

FILES

method	path	accepts	return keys	description
GET	/repos/:user/:repo /files	_		list all files in a repo
GET	/repos/:user/:repo /files/:file	_		download a file
POST	/repos/:user/:repo /files	_		upload a new file
DELETE	/repos/:user/:repo /files/:file	-		delete a file
POST	/repos/:user/:repo /tables?from_file=:filename	_		import a table from a file

CARDS

method	path	accepts	return keys	description
GET	/repos/:user/:repo /cards	_		list all cards in a repo
GET	/repos/:user/:repo /cards/:card	_		view a card's info
POST	/repos/:user/:repo /cards	_		create a new card
DELETE	/repos/:user/:repo /cards/:card	-		delete a card
POST	/repos/:user/:repo /tables?from_card=:cardname	_		export a card to a table

QUERY

method	path	accepts	return keys	description
GET	/query/:user	{'sql'}	{'status', 'row_count', 'rows': [[]], 'columns' [{'type', 'name'}]}	execute SQL in :user's database
GET	/query/:user/:repo	{'sql'}	see above	execute SQL in :user's database where every table is assumed to be in :repo

##HTTP methods

### REST convention
- GET for reading
- POST for creating
- DELETE for removing
- PUT for replacing a whole thing
- PATCH for changing part of a thing

###Alternative for GET-only clients

Developers can explore (but not necessarily use) the API entirely through their web browser with GET requests, e.g. `GET /repos/:user`.

##Request authorization

All endpoints are sensitive, so all requests require HTTPS and an OAuth bearer token in their Authorization request header or in an `access_token` query parameter.

##Formats

###Specifying a desired response format

- Request header `Accept: "application/json"`
- URL extension `/repos.json`
- Query param `/repos?format=json`

Accept headers are the usual convention, but for clients that can't set headers it would be good to offer common alternatives. We may want to support XML and other formats eventually, but JSON should be the default.

###Supported request formats for POST, PUT, PATCH

- application/json
- application/x-www-form-urlencoded
- multipart/form-data

Supporting HTML form content types would make it possible for authenticated clients to use DataHub directly for form actions. POST data doesn't survive redirects through the OAuth approval process, so the client app would need to already have a valid OAuth token for this to work.