/grabbag

Link-saving application, a la Instapaper

Primary LanguagePython

What the?

This is a Django app for saving links to read later, similar to Pocket or Instapaper. Currently barebones, but check back later (it still won’t have the features you want).

But… why?

Because Instapaper and Pocket weren’t invented here, obviously. Also because Wallabag was too much trouble to set up. This will be too much trouble to set up as well, but at least it’s my trouble.

Ok, fine, but how?

Make sure you’ve got LINKSAVE_MASTER_API_TOKEN set in the settings file (can be any string up to 100 characters), then do whatever it is you do to run Django apps. Once it’s running, use the API endpoints to do useful things (you didn’t think this was going to be user-friendly, did you?)

You may also need to alter your server settings to enable passthrough of the Authorization header to support the API authentication system (this is the WSGIPassAuthorization option for mod_wsgi).

Features

  • API endpoints!
  • no UI to speak of!
  • hand-rolled auth system!
    • because who needs builtin framework modules, am I right?
      • …no? Ok, so it’s just me, then.
  • API authentication system that is nearly, but not quite, entirely unlike OAuth 2.
  • capabilities-based API authorization system

Docs

Running tests

Tests can be run by issuing make unittest from the grabbag directory.

API endpoints

The API endpoints are located at urls under /api/v1/ (where v1 might be something else if another version of the API is ever done). Clients must present a valid API token with the Authorization: Bearer <token> header. If the header is not present, or the token is invalid, the endpoint will return a 401 response. If the token is not authorized to perform the action in question, a 401 response will also be returned. All endpoints return data in JSON form.

List API Tokens

  • Endpoint: tokens/
  • Method: GET, HEAD
  • Scope: admin
  • Return data: list of tokens (strings)

This method returns a list of all API tokens in the system.

Create Admin Token

  • Endpoint: tokens/new/
  • Method: POST
  • Submit data: none
  • Scope: admin
  • Return data: the newly created token (string)

Creates a new API token with administrative privileges, and returns its ID. The resulting token is suitable for use in the Authorization header after this call is complete.

Create User Token

  • Endpoint: users/<id>/tokens/new/
  • Method: POST
  • Submit data: none
  • Scope: user, admin
  • Return data: the newly created token (string)

Creates a new token scoped to the user named by <id>. A user token may only be used to create user tokens for the original tokens user (i.e. a user can create more tokens for themselves, but not other users).

List Users

  • Endpoint: users/
  • Method: GET, HEAD
  • Scope: admin
  • Return data: a list of user objects, with the keys “id”, “username”, “email”, and “password”.

This endpoint lists all the users in the system. In the result data, the value for the “password” key is always null

List Single User

  • Endpoint: users/<id>/
  • Method: GET, HEAD
  • Scope: admin
  • Return data: a user object, with keys “id”, “username”, “email”, and “password”.

This endpoint is like the list users endpoint, except it only returns data for a single user named by the <id> parameter. Returns a 404 if there is no user with that id.

Create User

  • Endpoint: users/new/
  • Method: POST
  • Scope: admin
  • Submit data: a user object, with keys “username”, “email”, and “password”. All other keys are ignored.
  • Return data: new user’s id

This method creates a new user in the system with the specified username, email, and password. If a user with the same username already exists, a 409 response is returned. If any of the required keys are missing, or if they are not of the expected type, a 400 response is returned.

Delete User (POST)

  • Endpoint: users/<id>/delete/
  • Method: POST
  • Scope: user or admin
  • Submit data: none
  • Return data: none

This method deletes the user named by the id parameter. If there is no such user, a 404 is returned, otherwise a 200. This endpoint may be used with admin tokens, or with a user token that was issued for the user named by id. A user token may not be used to delete any user other than the token’s.

Delete User (DELETE)

  • Endpoint: users/<id>/
  • Method: DELETE
  • Scope: user or admin
  • Submit data: none
  • Return data: none

Same as the POST method for deleting users, only a different interface for the operation. Delightfully RESTful.

Update User (PATCH)

  • Endpoint: users/<id>/
  • Method: PATCH
  • Scope: user or admin
  • Submit data: a subset of fields from a user create call
  • Return data: updated user object (see user listing)

A PATCH call to the endpoint updates the user values specified in the request, leaving other values unchanged. The updated user object is returned in the response. A user token may only be used to update the user the token is for.

Update User (POST)

  • Endpoint: users/<id>/update/
  • Method: POST
  • Scope: user or admin
  • Submit data: a subset of fields from a user create call
  • Return data: updated user object (see user listing)

Same as the PATCH user update endpoint, only via POST.