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).
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.
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).
- 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.
- because who needs builtin framework modules, am I right?
- API authentication system that is nearly, but not quite, entirely unlike OAuth 2.
- capabilities-based API authorization system
Tests can be run by issuing make unittest
from the grabbag
directory.
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.
- 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.
- 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.
- 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).
- 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.