Catalog API

A data catalog service for awesome data.

Screenshots

Run

Python 3.5+

• Prepare database

CREATE DATABASE IF NOT EXISTS catalogdb DEFAULT CHARSET utf8 COLLATE utf8_general_ci;

• Run development server

./devtools/run_server.sh

Swagger UI: localhost:4444/api/v1

Quickstart

Open online interactive API documentation: http://127.0.0.1:4444/api/v1/

Autogenerated swagger config is always available from http://127.0.0.1:4444/api/v1/swagger.json

catalog.db (SQLite) includes 2 users:

• Admin user root with password q
• Regular user catalog with password w

NOTE: Use On/Off switch in documentation to sign in.

Authentication Details

This example server features OAuth2 Authentication protocol support, but don't be afraid of it! If you learn it, OAuth2 will save you from a lot of troubles.

Authentication with Login and Password (Resource Owner Password Credentials Grant)

Here is how you authenticate with user login and password credentials using cURL:

$ curl 'http://127.0.0.1:4444/auth/oauth2/token?grant_type=password&client_id=catalog&username=root&password=q'
{
  "access_token": "pzBVnebw56mGgJWnC9D6maVLYxbrwX",
  "expires_in": 3600,
  "refresh_token": "3BvmXnE6YWObFcevMf9CdwiyHExozz",
  "scope": "auth:read auth:write users:read users:write comments:read comments:write datasets:read datasets:write stories:read stories:write",
  "token_type": "Bearer"
}

That is it!

Well, the above request uses query parameters to pass client ID, user login and password which is not recommended (even discouraged) for production use since most of the web servers logs the requested URLs in plain text and we don't want to leak sensitive data this way. Thus, in practice you would use form parameters to pass credentials:

$ curl 'http://127.0.0.1:4444/auth/oauth2/token?grant_type=password' -F 'client_id=catalog' -F 'username=root' -F 'password=q'

, or even pass client_id as Basic HTTP Auth:

$ curl 'http://127.0.0.1:4444/auth/oauth2/token?grant_type=password' --user 'catalog:' -F 'username=root' -F 'password=q'

You grab the access_token and put it into Authorization header to request "protected" resources:

$ curl --header 'Authorization: Bearer pzBVnebw56mGgJWnC9D6maVLYxbrwX' 'http://127.0.0.1:4444/api/v1/users/me'
{
    "id": 1,
    "username": "root",
    "email": "root@localhost",
    "first_name": "",
    "middle_name": "",
    "last_name": "",
    "is_active": true,
    "is_regular_user": true,
    "is_admin": true,
    "created": "2016-10-20T14:00:35.912576+00:00",
    "updated": "2016-10-20T14:00:35.912602+00:00"
}

Once the access token expires, you can refresh it with refresh_token. To do that, OAuth2 RFC defines Refresh Token Flow (notice that there is no need to store user credentials to do the refresh procedure):

$ curl 'http://127.0.0.1:4444/auth/oauth2/token?grant_type=refresh_token' --user 'catalog:' -F 'refresh_token=pzBVnebw56mGgJWnC9D6maVLYxbrwX'
{
    "token_type": "Bearer",
    "access_token": "YD5Rc1FojKX1ZY9vltMSnFxhm9qpbb",
    "refresh_token": "pzBVnebw56mGgJWnC9D6maVLYxbrwX",
    "expires_in": 3600,
    "scope": "auth:read auth:write users:read users:write comments:read comments:write datasets:read datasets:write stories:read stories:write"
}

Authentication with Client ID and Secret (Client Credentials Grant)

Here is how you authenticate with user login and password credentials using cURL:

$ curl 'http://127.0.0.1:4444/auth/oauth2/token?grant_type=client_credentials' --user 'catalog:KQ()SWK)SQK)QWSKQW(SKQ)S(QWSQW(SJ*HQ&HQW*SQ*^SSQWSGQSG'
{
    "token_type": "Bearer",
    "access_token": "oqvUpO4aKg5KgYK2EUY2HPsbOlAyEZ",
    "expires_in": 3600,
    "scope": "auth:read auth:write users:read users:write comments:read comments:write datasets:read datasets:write stories:read stories:write"
}

The same way as in the previous section, you can grab the access_token and access protected resources.

Reference:

• FrictionlessData

• Real-life RESTful server example on Flask-RESTplus

Author

Xiaming C. chenxm35@gmail.com