Skip to content

API.md

Latest commit

 

History

History
383 lines (266 loc) · 7.87 KB

API.md

File metadata and controls

383 lines (266 loc) · 7.87 KB
Raw

Wcms API documentation

Authentication

Using a token

W support Bearer Authentication.

To authenticate a request, present a token in the Authorization HTTP Header, after the Bearer keyword :

Authorization: Bearer <token>

To get, a token, you have to use the auth route.

Page related api

access

To access a page means to get the full JSON page object. User needs to be allowed to edit the coresponding page in order to access it.

GET     /api/v0/page/<page_id>

possible error codes:

  • 401 if user does'nt have the rights to access the page
  • 404 if page is not found
  • 406 in case of invalid ID

update

To update a page, you'll have to provide some fields of Page data. Only the given fields will be updated. The datemodified field is important as it's used for conflict detection. It has to be the same as stored Page, otherwise, a 409 response is thrown. An optional force=1 search parameter can be added to bypass conflict detection.

In case of success, you will get a 200 HTTP CODE and recieve the full JSON page object. The datemodif and editcount field will be updated.

POST    /api/v0/page/<page_id>/update[?force=1]

possible error codes:

  • 400 if the POST datas are not recieved or in case of JSON decoding error
  • 401 if user does'nt have the rights to update the page
  • 404 if page is not found
  • 406 in case of invalid ID
  • 409 in case of conflict (someone or something else updated the page before you)
  • 500 server error

add

To create a page, just send this request using the desired page ID.

POST    /api/v0/page/<page_id>/add

Optionaly, you can provide a JSON page object that will be used for the newly created page.

possibles error codes:

  • 401 if user does'nt have the rights to create the page
  • 405 if page already exist with this ID
  • 406 in case of invalid ID
  • 500 server error while saving page

put

This will create a page if not existing or erase an existing one with given JSON. datecreation will be reset if it already existed.

PUT     /api/v0/page/<page_id>

possibles success codes:

  • 200 if the page already existed and has been successfully overiden.
  • 201 if the page was created created

possibles error codes:

  • 401 if user does'nt have the rights to update/create the page
  • 406 in case of invalid ID
  • 500 server error while saving page

delete

To delete a page, just send this request using the desired page ID.

DELETE  /api/v0/page/<page_id>

possibles error codes:

  • 401 if user does'nt have the rights to delete the page
  • 404 if page is not found
  • 406 in case of invalid ID
  • 500 server error

list

List all pages IDs. This method is way more efficient than the query version.

GET     /api/v0/pages/list

possibles error codes:

  • 401 if user does'nt have the rights to view list of page

example response

{
    "pages": [
        "kitchen", "about-love", "22", "morbier", "birthday-2034"
    ]
}

query

List pages ID using filters and sorting options.

POST    /api/v0/pages/query

You need to provide a JSON representing search options. Those are the same as the Web interface options.

An extra key fields define which field will be outputed. If not present, all fields will be returned. Provide an empty array if you want no field.

All the keys are optionnal.

possible error codes:

  • 400 if the POST datas are not recieved or in case of JSON decoding error
  • 401 if user does'nt have the rights to view list of page

example request

{
    "fields": ["datemodif", "version"],
    "sortby": "datemodif",
    "order": 1,
    "tagfilter": ["cc", "dille"],
    "tagcompare": "AND",
    "tagnot": false,
    "authorfilter": ["vincent", "audrey"],
    "authorcompare": "OR",
    "secure": 0,
    "linkto": "the-pagest-page",
    "invert": false,
    "limit": 2,
    "since": "2022-12-09T23:27",
    "until": "2025-01-01T10:10"
}

example response

{
    "pages": {
        "about-love": {
            "datemodif": "2022-12-09T23:27",
            "version": 2
        },
        "morbier": {
            "datemodif": "2021-06-09T13:33",
            "version": 2
        }
    }
}

User related API

get

Retrieve an user as a JSON object

GET     /api/v0/user/<userid>

possible error codes:

  • 401 if user is'nt an admin
  • 404 if user is not found

Media related API

upload

Upload a file. Specify a target <path> and send the file through the body of the request. Folders will be created automatically.

POST    /api/v0/media/upload/<path>

possible error codes:

  • 400 If a error occured while reading the file stream or when creating the file/folders
  • 403 if user is'nt an editor
  • 406 if user is not found

Public API

version

Return 200 if W instal is healthy.

GET     /api/v0/version

{
    "version": "v2.3.0"
}

auth

Return 200 in case of auth success.

POST    /api/v0/auth

possible error codes:

  • 400 If auth failed

example request

{
    "username": "michel",
    "password": "ilovecrepes"
}

example response

{
    "token": "ddo3jsdjqsj:fgfpgoeaalkakn5eooddf:dpapajj235redao"
}

Schemas

Page

{
  "id": "bar",
  "title": "Bar (le duc)",
  "description": "ba bidou bap bap oh yeahhhhh",
  "lang": "",
  "tag": ["room", "enfer", "kroute"],
  "latitude": null,
  "longitude": null,
  "date": "2024-01-02T20:29:00+01:00",
  "datecreation": "2024-01-19T20:29:32+01:00",
  "datemodif": "2025-07-17T02:14:22+02:00",
  "daterender": "2025-07-16T19:35:10+02:00",
  "css": "",
  "javascript": "",
  "body": "<main>%CONTENT%</main>",
  "externalcss": [],
  "customhead": "",
  "secure": 0,
  "interface": "content",
  "linkto": [],
  "templatebody": "",
  "templatecss": "",
  "templatejavascript": "",
  "favicon": "",
  "thumbnail": "",
  "authors": ["vincent", "audrey"],
  "displaycount": 31,
  "visitcount": 3,
  "editcount": 63,
  "sleep": 0,
  "redirection": "",
  "refresh": 0,
  "password": "",
  "postprocessaction": false,
  "externallinks": [],
  "version": 2,
  "content": "Un bar! Binjour"
}

Usages example

Update a page element.

obj = await fetch('http://localhost:8080/api/v0/page/jardin')
    .then(res => res.json());
obj.main += "foobar";
fetch('http://localhost:8080/api/v0/page/jardin/update', {
    method: "POST",
    body: JSON.stringify(obj),
})
    .then(res => res.text())
    .then(console.log);

Get the list of all pages.

obj = await fetch('http://localhost:8080/api/v0/pages/list')
    .then(res => res.json());

Get the list of pages

const options = {sortby:"datemodif", limit: 40, tagfilter: ["galaxy", "sublime"]};
fetch('http://localhost:8080/api/v0/pages/query', {
    method: "POST",
    body: JSON.stringify(options),
})
    .then(res => res.json())
    .then(console.log);

Create a page with generated ID

HTML

<button id="create-page">Create a new page</button>

Javascript

document.querySelector('button#create-page').addEventListener('click', function(){
    const random = Math.floor(Math.random() * 1000) + 1;
    var url = "/api/v0/page/" + random;

    var promise = fetch(url, {
        method: "PUT",
        body: JSON.stringify({
            id: random,
            tag: ['generated'],
            description: 'This page has been generated thanks to the API',
            title: 'Page n°' + random,
        }),
    })
    promise.then(function(response) {
        if (response.ok) {
            alert('The page has been created !');
        } else {
            alert('erreur: ' + response.status);
        }
    });
});