API: Visão geral e configuração

1Introdução

Neste tutorial, vamos ver como criar uma API. Isso vai permitir que serviços externos se conectem a um serviço de gerenciamento de bloco de notas.

A API oferece as seguintes funcionalidades:

  • Listar as notas do usuário.
  • Listar as tags vinculadas às notas.
  • Buscar notas usando critérios (tag, data, título).
  • Recuperar o conteúdo de uma nota pessoal.

2Configuração

Este desenvolvimento usa o plugin Api fornecido pelo Temma. Como indicado na documentação, o plugin deve ser adicionado ao arquivo de configuração, junto com a configuração da conexão ao banco de dados e a desativação das sessões: 

<?php

return [
    'application' => [
        // configuração do banco de dados
        'dataSources' => [
            'db' => 'mysql://user:password@localhost/dbase'
        ],
        // desativação das sessões
        'enableSessions' => false,
    ],
    // ativação do plugin Api
    'plugins' => [
        '_pre' => [
            '\Temma\Plugins\Api',
        ],
    ],
];

Você pode pensar que seria preciso adicionar uma instrução à configuração para definir a visão JSON como visão padrão. O plugin Api cuida disso.

Para gerenciar a autenticação dos usuários que se conectam à API, o plugin usa um sistema de par de chaves pública/privada. Os usuários e as chaves são armazenados em um banco de dados. Consulte a documentação do plugin para conhecer os detalhes das tabelas a serem criadas.

3Rotas

A API propõe uma abordagem RPC, com uma rota para cada ação possível. Isso é mais simples do que a abordagem REST, na qual a mesma rota executa ações diferentes dependendo do método HTTP usado para chamá-la.

O plugin da API gerencia as versões da API. As URLs são, portanto, prefixadas com "/v1", para representar a primeira versão da API.

A API vai propor as seguintes URLs:

  • /v1/tag/list: Retorna uma lista de tags.
  • /v1/note/list: Retorna uma lista de notas.
  • /v1/note/search: Busca notas com base em critérios.
  • /v1/note/get/[id]: Recupera o conteúdo de uma nota.
  • /v1/note/add: Cria uma nova nota.
  • /v1/note/update/[id]: Modifica uma nota.
  • /v1/note/remove/[id]: Exclui uma nota.

Se a autenticação não estiver correta, um erro HTTP 401 é retornado.
Se um usuário autenticado tentar acessar um recurso que não lhe pertence, um erro HTTP 403 é retornado.

3.1/v1/tag/list

Retorna a lista de tags usadas pelas notas do usuário, com o número de notas correspondentes a cada tag.

Exemplo de retorno (formato JSON):

{
    "informatica": 1,
    "web": 1,
    "culinaria": 1
}

3.2/v1/note/list

Retorna a lista de notas do usuário.

Exemplo de retorno (formato JSON):

[
    {
        "id": 123,
        "title": "Sites interessantes",
        "tags": ["informatica", "web"],
        "creation": "2024-01-01 12:00:00",
        "update": "2024-02-01 16:00:00"
    },
    {
        "id": 456,
        "title": "Cursos de culinária online",
        "tags": ["culinaria", "web"],
        "creation": "2025-01-01 10:00:00",
        "update": "2025-01-01 10:00:00"
    }
]

Retorna uma lista de notas pertencentes ao usuário, obtida a partir de critérios fornecidos em parâmetros GET.

Parâmetros possíveis (todos opcionais):

  • tag (string): Tag associada às notas.
  • title (string): String a buscar no título das notas.

A resposta é semelhante à da URL /note/list.

3.4/v1/note/get/[id]

Retorna todos os dados de uma nota cujo identificador é passado como parâmetro na URL.

Exemplo de retorno (formato JSON):

{
    "id": 123,
    "title": "Sites interessantes",
    "tags": ["informatica", "web"],
    "creation": "2024-01-01 12:00:00",
    "update": "2024-02-01 16:00:00",
    "content": "<p>Pequena lista de sites:</p>
<ul>
  <li><a href=\"https://www.temma.net/\">Temma</a></li>
</ul>"
}

Se a nota solicitada não pertencer ao usuário, um erro HTTP 403 é retornado.

3.5/v1/note/add

Cria uma nova nota, usando dados fornecidos em parâmetros POST ou GET.

Parâmetros esperados (todos obrigatórios):

  • title (string): Título da nota.
  • tag (string | array): Tag ou lista de tags a associar à nota.
  • content (string): Conteúdo da nota em formato HTML.

Para fornecer uma lista de tags, envie vários parâmetros chamados tag[].

Esta URL retorna o identificador da nota criada.

3.6/v1/note/update/[id]

Atualiza os dados da nota cujo identificador é fornecido como parâmetro na URL.

A atualização usa os dados fornecidos como parâmetro POST ou GET. Cada parâmetro é opcional, e um parâmetro fornecido substitui o valor salvo.

Os parâmetros possíveis são:

  • title (string): Título da nota.
  • tag (string | array): Tag ou lista de tags a associar à nota.
  • content (string): Conteúdo da nota em formato HTML.

Para fornecer uma lista de tags, você precisa enviar vários parâmetros chamados tag[].

Esta URL retorna true em caso de sucesso.

Se a nota solicitada não pertencer ao usuário, um erro HTTP 403 é retornado.

3.7/v1/note/remove/[id]

Exclui a nota cujo identificador é fornecido como parâmetro na URL.

Esta URL retorna true em caso de sucesso.

Se a nota solicitada não pertencer ao usuário, um erro HTTP 403 é retornado.