This repository has been archived on 2022-07-19. You can view files and clone it, but cannot push or open issues or pull requests.
dotplan-online/README.md

74 lines
3.4 KiB
Markdown
Raw Normal View History

2020-07-16 20:48:53 -05:00
# dotplan.online
## The un-social network.
- User-provided content tied to an email address.
- Text only, limited to 4kb.
- No retweets, shares, @s, likes, or boosting of any kind.
2020-07-16 23:55:59 -05:00
- Authenticity optionally verified by clients using public PGP keys.
2020-07-16 20:48:53 -05:00
- Accessed via public APIs.
2020-07-16 23:55:59 -05:00
- Open source.
- Self-hostable, discovery via domain SRV records.
2020-07-16 20:48:53 -05:00
## API
2020-07-19 09:28:37 -05:00
Any dotplan implementation should expose at least the following two endpoints:
- `GET /plan/{email}` - retrieve a plan
- `text/plain` by default - raw plan content
- `?format=html` or `Accept: text/html` - plan content with html entity encoding for special characters
- `?format=json` or `Accept: application/json`:
- `plan` - raw plan content
- `signature` - ascii armored PGP signature if this plan was signed
- `timestamp` - when this plan was created
- `404` if no plan found
- `301` redirect if domain SRV record indicates plan is on a different dotplan provider
2020-07-19 13:15:26 -05:00
- This is optional for servers to act as relays, in practice the client should look up the SRV record itself
2020-07-19 09:28:37 -05:00
- `POST /verify/{email}` - verify PGP signature of a plan
- request json data:
- `pubkey` - ascii armored public PGP key to verify the signature with
- response json data:
- `verified` - `1` or `0` depending on whether verification of the plan signature was successful
- normal plan details included if `verified=1`
- `403` if server-side verification is not supported
- `404` if no plan found
- `308` redirect if domain SRV record indicates plan is on a different dotplan provider.
2020-07-19 13:15:26 -05:00
- This is optional for servers to act as relays, in practice the client should look up the SRV record itself.
2020-07-19 09:28:37 -05:00
2020-07-16 23:55:59 -05:00
### Authentication
2020-07-19 09:28:37 -05:00
The reference dotplan implementation also exposes these endpoints for account management and authentication. Other implementations may differ and offer other authentication mechanisms (OAuth2 for example, or supporting the creation and invalidation of multiple authentication tokens).
2020-07-16 23:55:59 -05:00
- `POST /users/{email}` - request new account
2020-07-19 09:28:37 -05:00
- request json data:
- `password` - the password for the new account
- an email with a validation link will be sent
- `PUT /users/{email}` - validate new account
- request json data:
- `token` - the validation token from the email
2020-07-17 21:36:12 -05:00
- `GET /token` - retrieve auth token
2020-07-16 23:55:59 -05:00
- http basic auth
2020-07-17 21:36:12 -05:00
- `?expires={minutes}` sets an explicit expiration, default is 5 minutes from creation
2020-07-19 09:28:37 -05:00
- response json data:
- `token` - the authentication token
2020-07-17 21:36:12 -05:00
- `DELETE /token` - invalidate current auth token
2020-07-16 23:55:59 -05:00
- http basic auth
2020-07-19 09:28:37 -05:00
- `GET /users/{email}/pwchange` - get password change token
- an email with a password change token will be sent
2020-07-16 23:55:59 -05:00
- token expires 600 seconds from creation
2020-07-19 09:28:37 -05:00
- `PUT /users/{email}/pwchange` - update password
- request json data:
- `password` - the new password
- `token` - the password change token from the email
### Updating a Plan
2020-07-16 23:55:59 -05:00
2020-07-19 09:28:37 -05:00
The reference dotplan implementation exposes this endpoint to update a plan using a given authentication token. Other implementations may differ and offer other mechanisms to update a plan (by email or text message for example, or integration with other services).
2020-07-16 23:55:59 -05:00
- `PUT /plan/{email}` - update a plan
2020-07-19 09:28:37 -05:00
- request json data:
- `plan` - optional new plan content
- `signature` - optional ascii encoded PGP signature
- `auth` - the authentication token
2020-07-17 21:36:12 -05:00
- omitting `plan` from the payload will delete the existing plan