Todos Simple API

a simple API to test and prototype todo front end applications

Create, read, update, and delete todos all from an easy-to-use API. Includes user account functionality. Just provide an email and you should receive your api key in your inbox a few moments later. Full documentation provided using Swagger and OpenApi 3.0. Sign up today!

Get Started!

Getting Started

There are two ways to use the API: Via general non-user general todos CRUD api operations, or for a little more complexity, and to give developers an opportunity to play around with bearer token authentication, via registering users, and then tying all CRUD todo operations to users specifically. There is currently a limit of 100 general todos, a limit of 25 todos per user account, and a limit of 10 users per apikey.

Generic Todos

Once you have registered for your own api key, it's easy to get started. Here's the supported methods:

Retrieve all todos: GET /api/todos?apikey=xxxxxxxxxxxxxx
Retrieve specific todo: GET /api/todos/{id}?apikey=xxxxxxxxxxxxxx
Create new todo: POST /api/todos?apikey=xxxxxxxxxxxxxx
Update an existing todo: PUT /api/todos/{id}?apikey=xxxxxxxxxxxxxx
Delete an existing todo: DELETE /api/todos/{id}?apikey=xxxxxxxxxxxxxx
Delete all todos: DELETE /api/todos?apikey=xxxxxxxxxxxxxx

Below is what the standard body in a POST or PUT should look like. The meta tag and completed flags are optional. The meta property, if used, must be in JSON format, not exceeding 256 bytes. Meta can be a useful field to store additional data for the todo.

{
    "description": "Buy Milk",
    "completed": false,
    "meta":
        {
            "assigned_to": "bob",
            "priority": "low",
            "notes": "really need to get this completed"
        }
}

User Accounts

To get started users will be required to register with email and password, the POST should include:

{
    "name": "Joe Smith",
    "email": "joe@smith.com",
    "password": "12345678"
}

If successful, the following response will contain the token:

{
    "name": "John Smith",
    "email": "joe@smith.com",
    "enabled": true,
    "token": "14a6be7a-d00b-44e6-a0f1-c0ebd6171936",
    "admin": false,
    "id": 1
}

Every subsequent call must now include the Authorization header with the bearer token:

Authorization: Bearer 14a6be7a-d00b-44e6-a0f1-c0ebd6171936

The calls to the users based todos api are very similar to the generic todos api, the url now just needs to include the /users/{user_id} prefix, like this:

https://todos.simpleapi.dev/api/users/3/todos?apikey=xxxxxxxxxxxxxxxxxxxxx

Admin User Account

If a user registers with the same email that was used to register the apikey, that user is automatically registered as an admin user, with elevated rights, including listing users and deleting one or all users. This is a sample response to such a registration:

{
    "name": "Happy Dev",
    "email": "happydev@devological.me",
    "enabled": true,
    "token": "b3fb015d-5ab3-4b8e-9d30-48fe8d060321",
    "admin": true,
    "id": 2
}

Admin users can include the query parameter

?admin=true

when calling the delete all users method that will also remove their account and log them out. Registering with the same email again will restore them as admins.

Bugs, Issues, Requests, Feedback

Chances are things will come up, be it bugs or ideas. We welcome your feedback. Please post your comments here on our Github page.