justinanderson/datahub_rest_api.md

## datahub_rest_api.md

      
    Raw
  

              datahub_rest_api.md
            
          
    This is a shallow pass at designing DataHub's REST API. This covers how requests could work and doesn't yet consider responses. This is also just a mapping of DataHub's current functionality and doesn't consider new permissions models or other functionality.
The list below leaves out most parameters each endpoint would take, like the name of a new repo, to keep the list readable.
##Endpoints
GET    /user               # get current user's name
GET    /user/repos         # get current user's repos
GET    /repos              # get all repos visible to current user

GET    /repos/:user        # list all of a user's repos
POST   /repos/:user        # create a repo
DELETE /repos/:user/:repo  # delete a repo
PATCH  /repos/:user/:repo  # rename a repo

GET    /repos/:user/:repo/collaborators                # list all collaborators of a repo
PUT    /repos/:user/:repo/collaborators/:collaborator  # add a collaborator
DELETE /repos/:user/:repo/collaborators/:collaborator  # remove a collaborator

GET    /repos/:user/:repo/tables                       # list all tables in a repo
GET    /repos/:user/:repo/tables/:table                # view a table's info
POST   /repos/:user/:repo/tables                       # create a new table
DELETE /repos/:user/:repo/tables/:table                # delete a table
POST   /repos/:user/:repo/files?from_table=:tablename  # export a table to a file

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

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

GET    /query/:user/?sql=:query                        # execute SQL in :user's database
GET    /query/:user/:repo/?sql=:query                  # 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
This could be a security vulnerability, but it might be useful for developers to be able to explore the API entirely through their web browser with GET requests, e.g. GET /repos/:user?method=POST.
##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.