Document the REST API

[abunsen]

Hey guys, is there a public API to get the data I have queried in Metabase to external services, like zapier?

[tlrobinson]

Define "public" :)

You are more than welcome to use the same RESTful/HTTP/JSON API we use to implement the frontend, however it is not yet well documented and we haven't made any promises about backwards compatibility in future versions (though we tend to not break existing APIs)

Right now the easiest way to figure out the API is to look at the Clojure source in src/metabase/api and to watch the requests in your browser's network traffic inspector.

Here's an example: http://discourse.metabase.com/t/external-http-api/175/5

And here's the query language reference: https://github.com/metabase/metabase/wiki/Query-Language-%2798

I'll change the title to say we should document the API.

[abunsen]

Thank you! I ended up doing something like that (in Python):

import json 

headers = {
    'Accept-Language': 'en-US,en;q=0.8',
    'Origin': 'http://mymetabase.herokuapp.com',
    'Host': 'mymetabase.herokuapp.com',
    'Cookie': 'metabase.SESSION_ID=XXXXXXXX',
    'Referer': 'http://mymetabase.herokuapp.com/q/b64stringhere',
    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102 Safari/537.36',
    'Content-Type': 'application/json;charset=UTF-8'
}

payload = {
    "database":2,
    "type":"native",
    "native": {
        "query": "LONG SQL QUERY;"
    }
}
url = 'http://mymetabase.herokuapp.com/api/dataset'
r = requests.post(url, data=json.dumps(payload), headers=headers)

output = json.loads(r.text)

[tlrobinson]

BTW, I believe sessions will expire after 2 weeks.

I'd also recommend doing this over HTTPS, which should work out of the box on Heroku.

[camsaul]

You can always run lein instant-cheatsheet to see automatically generated documentation for all of Metabase's API endpoints, e.g.

You can view various endpoints by searching for GET, PUT, POST, or DELETE. It's not a comprehensive guide to using the API but since we don't have one at the moment it's our closest alternative.

[camsaul]

Another good starting point is looking at services.js which lists all the endpoints used by the frontend (albeït without much documentation).

[camsaul]

Since this question is being asked in a lot of places let me summarize how to use the API again:

Get a session token by hitting POST /api/session

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "cam@metabase.com", "password": "myPassword"}' \
  http://localhost:3000/api/session 

# -> {"id":"38f4939c-ad7f-4cbe-ae54-30946daf8593"}

Pass that session token as a X-Metabase-Session header to other endpoints

curl -X GET \
  -H "Content-Type: application/json" \
  -H "X-Metabase-Session: 38f4939c-ad7f-4cbe-ae54-30946daf8593" \
  http://localhost:3000/api/user/current

# -> {"email":"cam@metabase.com","first_name":"Cam", ...}

[kqiu2]

I'm trying to run a query from the command line that gets the sum of all prices in the products table (i.e. source_table 3) from the given sample dataset (i.e. database 1). This is how it looks in SQL:
SELECT sum("PUBLIC"."PRODUCTS"."PRICE") AS "sum" FROM "PUBLIC".”PRODUCTS"

This is what I executed in the terminal:
curl -X Post -H "Cookie: metabase.SESSION_ID=XXXXXX" -H "Content-Type: application/json" -d '{"database": 1, "type":"query", "query": {"source_table": 3, "aggregation": ["sum" 25], "breakout": [], "filter": []}}' http://localhost:3000/api/dataset

However, it returned a "Malformed JSON in request body" error. I've tried changing up the ["sum" 25] part, like adding brackets, getting rid of the quotation marks, adding a colon, putting field-id in front of 25, etc, but nothing has worked. Does anyone have an idea of what my syntax error is?

[camsaul]

"Malformed JSON in request body" means exactly what it says... ["sum" 25] isn't valid JSON; you're missing a comma.

It's probably easier to edit your JSON in an editor that validates the syntax and then copy that into the command line.

[camsaul]

I've written an official wiki page consolidating the vast troves of wisdom contained on this page. View the guide to using the REST API here:

https://github.com/metabase/metabase/wiki/Using-the-REST-API

This page also has a link to our new complete list of API endpoints from PR #3630.

Since this is now implemented I'm going to go ahead and close this out.