API: Overview and configuration

1Introduction

In this tutorial, we'll look at how to create an API. This will enable external services to connect to a notepad management service.

The API offers the following functionalities:

  • List the user's notes.
  • List tags linked to notes.
  • Search for notes using criteria (tag, date, title).
  • Retrieve the content of a personal note.

2Configuration

This development uses the Api plugin supplied by Temma. As indicated in the documentation, the plugin must be added to the configuration file, along with the database connection configuration and the deactivation of sessions: 

<?php

return [
    'application' => [
        // database configuration
        'dataSources' => [
            'db' => 'mysql://user:password@localhost/dbase'
        ],
        // session disabling
        'enableSessions' => false,
    ],
    // activation of the Api plugin
    'plugins' => [
        '_pre' => [
            '\Temma\Plugins\Api',
        ],
    ],
];

You might think that you'd have to add an instruction to the configuration to define the JSON view as the default view. The Api plugin takes care of this.

To manage the authentication of users connecting to the API, the plugin uses a public/private key system. Users and keys are stored in a database. Please refer to the plugin documentation for details of the tables to be created.

3Routes

The API proposes an RPC approach, with one route for each possible action. This is simpler than the REST approach, where the same route performs different actions depending on the HTTP method used to call it.

The API plugin manages API versions. URLs are therefore prefixed with "/v1", to represent the first version of the API.

The API will propose the following URLs:

  • /v1/tag/list: Returns a list of tags.
  • /v1/note/list: Returns a list of notes.
  • /v1/note/search: Search for notes based on criteria.
  • /v1/note/get/[id]: Retrieves the contents of a note.
  • /v1/note/add: Creates a new note.
  • /v1/note/update/[id]: Modifies a note.
  • /v1/note/remove/[id]: Deletes a note.

If authentication is not correct, an HTTP 401 error is returned.
If an authenticated user tries to access a resource that does not belong to him/her, an HTTP 403 error is returned.

3.1/v1/tag/list

Returns the list of tags used by the user's notes, with the number of notes corresponding to each tag.

Return example (JSON format):

{
    'computers': 1,
    'web': 1,
    'cooking': 1
}

3.2/v1/note/list

Returns the user's list of notes.

Return example (JSON format):

[
    {
        "id": 123,
        "title": "Interesting websites",
        "tags": ["computers", "web"],
        "creation": "2024-01-01 12:00:00",
        "update": "2024-02-01 16:00:00"
    },
    {
        "id": 456,
        "title": "Online cooking courses",
        "tags": ["cooking", "web"],
        "creation": "2025-01-01 10:00:00",
        "update": "2025-01-01 10:00:00"
    }
]

Returns a list of notes belonging to the user, obtained from criteria supplied in GET parameters.

Possible parameters (all optional):

  • tag (string): Tag associated with the notes.
  • title (string): String to search for in the notes title.

The response is similar to the /note/list URL.

3.4/v1/note/get/[id]

Returns all the data for a note whose identifier is passed as a parameter on the URL.

Example of return (JSON format):

{
    "id": 123,
    "title": "Interesting websites",
    "tags": ["computers", "web"],
    "creation": "2024-01-01 12:00:00",
    "update": "2024-02-01 16:00:00"
    "content": "<p>Short list of sites:</p>
<ul>
  <li><a href=\"https://www.temma.net/\">Temma</a></li>
</ul>"
}

If the requested note does not belong to the user, an HTTP 403 error is returned.

3.5/v1/note/add

Creates a new note, using data supplied in POST or GET parameters.

Expected parameters (all mandatory):

  • title (string): Note title.
  • tag (string | array): Tag or list of tags to associate with the note.
  • content (string): Content of the note in HTML format.

To supply a list of tags, send several parameters named tag[].

This URL returns the identifier of the note created.

3.6/v1/note/update/[id]

Updates the data of the note whose identifier is supplied as a parameter on the URL.

The update uses the data supplied as a POST or GET parameter. Each parameter is optional, and a supplied parameter replaces the saved value.

Possible parameters are:

  • title (string): Note title.
  • tag (string | array): Tag or list of tags to associate with the note.
  • content (string): Note content in HTML format.

To supply a list of tags, you need to send several parameters named tag[].

This URL returns true on success.

If the requested note does not belong to the user, an HTTP 403 error is returned.

3.7/v1/note/remove/[id]

Deletes the note whose identifier is supplied as a parameter on the URL.

This URL returns true on success.

If the requested note does not belong to the user, an HTTP 403 error is returned.