Skip to content

Latest commit

 

History

History
659 lines (430 loc) · 9.88 KB

api.md

File metadata and controls

659 lines (430 loc) · 9.88 KB
Raw

API

Introduction

Plainpad exposes a flexible REST API that will enable you to handle all the information of your installations through HTTP requests. The API is using JSON as its data transaction format and features many best practices in order to make the resources easily consumable.

Making Requests

The API supports Token based authentication which means that you will have to send the bearer token authentication header with every request you make. This way you can ensure that no passwords will be stolen during the requests. The API expects the username and password of an admin user.

You can get a new token by creating a new session by sending the user credentials as the payload. This is the actual request that takes place while logging the user in. After a successful session creation you will receive a token that can be used for every other request.

Header:

Athorization: Bearer {SESSION-TOKEN-HERE}

The API honors the REST architecture which means that the client can use various HTTP verbs in order to perform various operations on the available resources. For example, you should use a GET request for fetching resources, a POST for creating new and PUT for updating existing ones in the database. Finally, a DELETE request will remove a resource from the system.

GET requests accept some parameter helpers that enable the sort, search, pagination and minification of the response information. Take a look in the following examples:

Search

Provide the filter parameter to perform a search in the resource.

https://url/to/public/api.php/v1/notes?filter=keyword

Sort

Sort the results in ascending or descending direction by providing the respective sign and the property name to be used for sorting.

https://url/to/public/api.php/v1/notes?sort=id&direction=asc

You can provide up to three sorting fields which will be applied in the provided order.

Paginate

Paginate the result by providing the page parameter along with the optional length parameter that defaults to 20.

https://url/to/public/api.php/v1/notes?page=1&length=10

Minimize

If you need to get only specific values from each JSON resource provide the fields GET parameter with a list of the required property names.

https://url/to/public/api.php/v1/notes?fields=id,book,hash,notes

Expected Responses

Most of the time the API will return the complete requested data in a JSON string but there are some cases that the responses might not contain a message but always a proper HTTP status code.

Resources & URIs

Application

Retrieve

Returns information about the application and optionally an array of available updates.

Authorization

Not required

Request

  • GET /v1

Payload

Not required

Response

{
    "updates": []
}

Install

This will execute the database migrations if they were not executed yet.

Authorization

Required

URL

  • POST /v1

Payload

(Empty)

Response

200 OK

Update

This will install the latest updates if available.

Authorization

Required

URL

  • PUT /v1

Payload

(Empty)

Response

200 OK

Sessions

Create

Create a new session for the selected user.

Authorization

Not required

URL

  • POST /v1/sessions

Payload

{
    "email": "info@example.org",
    "password": "12345"
}

Response

201 Created

{
    "user_id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "expires_at": "2020-03-23 04:38:09",
    "token": "dFt3PPUho4B2hPfmbrjDjkSbtQGLpAFrJptfgKPJBXc2fPSVyWMAuFCOISnS"
}

Delete

Create a new session for the selected user.

Authorization

Not required

URL

  • DELETE /v1/sessions/{TOKEN}

Payload

Not required

Response

200 OK

Notes

List

List all user notes.

Authorization

Required

URL

  • GET /v1/notes

Payload

Not required

Response

200 OK

[
  {
        "id": "644d6d5f-6c42-4c28-b9c1-d25a14cd7903",
        "user_id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
        "content": "Content",
        "title": "Title",
        "pinned": false,
        "created_at": "2020-03-20 09:34:02",
        "updated_at": "2020-03-20 09:34:08"
    }
]

Retrieve

Retrieve a note resource.

Authorization

Required

URL

  • GET /v1/notes/{ID}

Payload

Not required

Response

200 OK

{
    "id": "644d6d5f-6c42-4c28-b9c1-d25a14cd7903",
    "user_id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "content": "Content",
    "title": "Title",
    "pinned": false,
    "created_at": "2020-03-20 09:34:02",
    "updated_at": "2020-03-20 09:34:08"
}

Create

Create a new note for the selected user.

Authorization

Required

URL

  • POST /v1/notes

Payload

{
    "id": "9ab18f31-ec8f-4022-a972-d66198ede704",
    "user_id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "title": "New Note",
    "content": "This is the new note content.",
    "pinned": false,
    "updated_at": "2020-03-22 16:42:25",
    "created_at": "2020-03-22 16:42:25"
}

Response

201 OK

{
    "id": "72e27310-c9d7-4584-b887-846beb8331d7",
    "user_id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "title": "New Note",
    "content": "This is the new note content.",
    "pinned": false,
    "updated_at": "2020-03-22 16:44:58",
    "created_at": "2020-03-22 16:44:58"
}

Update

Update an existing note for the selected user.

Authorization

Required

URL

  • POST /v1/notes/{ID}

Payload

{
    "title": "Updated Note",
    "content": "This is the updated note content.",
    "pinned": false
}

Response

201 OK

{
    "id": "72e27310-c9d7-4584-b887-846beb8331d7",
    "user_id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "title": "Updated Note",
    "content": "This is the updated note content.",
    "pinned": false,
    "updated_at": "2020-03-22 16:44:58",
    "created_at": "2020-03-22 16:44:58"
}

Delete

Delete an existing note for the selected user.

Authorization

Required

URL

  • DELETE /v1/notes/{ID}

Payload

Not Required

Response

200 OK

Users

List

List all user users.

Authorization

Required

URL

  • GET /v1/users

Payload

Not required

Response

200 OK

[
  {
      "id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
      "name": "John Doe",
      "email": "admin@example.org",
      "admin": true,
      "locale": "en-US",
      "view": "compact",
      "line": "full",
      "sort": "modified",
      "theme": "light",
      "encrypt": false,
      "created_at": "2020-03-12 20:07:08",
      "updated_at": "2020-03-22 15:51:24"
  }
]

Retrieve

Retrieve a note resource.

Authorization

Required

URL

  • GET /v1/users/{ID}

Payload

Not required

Response

200 OK

{
    "id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "name": "John Doe",
    "email": "admin@example.org",
    "admin": true,
    "locale": "en-US",
    "view": "compact",
    "line": "full",
    "sort": "modified",
    "theme": "light",
    "encrypt": false,
    "created_at": "2020-03-12 20:07:08",
    "updated_at": "2020-03-22 15:51:24"
}

Create

Create a new note for the selected user.

Authorization

Required

URL

  • POST /v1/users

Payload

{
	"name": "John Doe",
	"email": "user@exmaple.org",
	"password": "12345",
	"locale": "en-US",
	"view": "compact", 
	"line": "full",
	"sort": "modified",
	"theme": "light",
	"admin": false
}

Response

201 OK

{
    "id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "name": "John Doe",
    "email": "admin@example.org",
    "admin": true,
    "locale": "en-US",
    "view": "compact",
    "line": "full",
    "sort": "modified",
    "theme": "light",
    "encrypt": false,
    "created_at": "2020-03-12 20:07:08",
    "updated_at": "2020-03-22 15:51:24"
}

Update

Update an existing note for the selected user.

Authorization

Required

URL

  • POST /v1/users/{ID}

Payload

{
	"name": "John Doe",
	"email": "user@exmaple.org",
	"password": "12345",
	"locale": "en-US",
	"view": "compact", 
	"line": "full",
	"sort": "modified",
	"theme": "light",
	"admin": false
}

Response

200 OK

{
    "id": "e150a31c-5987-41d7-bd16-b42d87dd3bce",
    "name": "John Doe",
    "email": "admin@example.org",
    "admin": true,
    "locale": "en-US",
    "view": "compact",
    "line": "full",
    "sort": "modified",
    "theme": "light",
    "encrypt": false,
    "created_at": "2020-03-12 20:07:08",
    "updated_at": "2020-03-22 15:51:24"
}

Delete

Delete an existing note for the selected user.

Authorization

Required

URL

  • DELETE /v1/users/{ID}

Payload

Not Required

Response

200 OK

Recovery

Recover the password of an existing user (email is sent).

Authorization

Required

URL

  • POST /v1/users/recover

Payload

{
  "email": "user@example.org"
}

Response

200 OK

Settings

Update

Update the application settings.

Authorization

Required (only for admins)

URL

  • PUT /v1/settings

Payload

{
    "default_locale": "de-DE",
    "mail_driver": "smtp",
    "mail_host": "smtp.mailtrap.io",
    "mail_port": "2525",
    "mail_username": "",
    "mail_password": "",
    "mail_encryption": "tls",
    "mail_from_address": "hello@example.org",
    "mail_from_name": "Plainpad"
}

Response

200 OK

Retrieve

Retrieve the application settings.

Authorization

Required (only for admins)

URL

  • GET /v1/settings

Payload

Not required

Response

200 OK

{
    "default_locale": "de-DE",
    "mail_driver": "smtp",
    "mail_host": "smtp.mailtrap.io",
    "mail_port": "2525",
    "mail_username": "",
    "mail_password": "",
    "mail_encryption": "tls",
    "mail_from_address": "hello@example.org",
    "mail_from_name": "Plainpad"
}

Back