Documentação

A Joda API é dividida em serviços. Cada serviço disponibiliza um conjunto de ações. Como todos os serviços têm ações semelhantes, foi selecionado um serviço exemplo para conter uma documentação mais abrangente.

Foi escolhido o serviço ‘Bíblia’ para suportar essa documentação abrangente. A Bíblia é um exemplo de fácil compreensão e pode conter a maior parte das informações necessárias para os desenvolvedores compreenderem o funcionamento de Joda API.

Em casos mais específicos, consulte a documentação específica de cada serviço de Joda API.

Serviço Bíblia

O serviço Bíblia provê ao desenvolvedor um conjunto de ações para gerenciar as escrituras sagradas.

As ações se dão basicamente sobre as tabelas da camada de persistência. No nosso exemplo, a Bíblia sagrada, temos três tabelas básicas: Livro, Capítulo e Versículo.

Note que se trata de uma estrutura hierárquica, onde a entidade forte é Livro. Capítulo depende de Livro e Versículo depente de Capítulo. Assim, a entidade mais fraca, Versículo, é identificada por Livro – Capitulo – Versículo (p. e. Filipenses 2:5).

Requisições

As requisições do serviço são feitas via HTTPS e as respostas são obtidas em formato JSON. Assim, suporta qualquer plataforma, sistema ou ambiente. Podendo ser utilizado em computadores, smartphones, tabletes, etc.

Todas as requisições devem ser do tipo POST e deve ter como corpo de entrada um Token de login informado no formato JSON (veja como obter um token de login aqui ).

O endereço do host é: www.joda.com.br

Veja as ações para a tabela ‘Livro’:

Note que as ações “Criar Livro” e “Excluir Livro” são de uso restrito. O que faz sentido, no caso do nosso exemplo, pois os livros da bíblia são consolidados e não há necessidade de incluir novos livros na Bíblia ou excluir algum livro existente. Mas este exemplo serve para demonstrar os critérios de permissões de acesso. Embora a grande maioria dos usuários não devam ter acesso a essas ações, elas são necessárias para o gerenciamento do serviço. Em algum momento alguém incluiu os Livros. E em algum momento alguém poderá excluir determinado Livro para fazer uma potecial correção nos dados.

Exemplo de requisição:

https://www.joda.com.br/biblia/livro/pesquisar.php?s=Gênesis

Veja o código da requisição no Postman:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

POST /biblia/livro/pesquisar.php?s=Gênesis HTTP/1.1
Host: www.joda.com.br
Content-Type: application/json
Proxy-Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxx=
Authorization: Basic xxxxxxxxxxxxxxxxxxxx
User-Agent: PostmanRuntime/7.18.0
Accept: */*
Cache-Control: no-cache
Postman-Token: xxxx
Host: joda-api-php-1.appspot.com
Accept-Encoding: gzip, deflate
Content-Length: 428
Connection: keep-alive
cache-control: no-cache
 
{
	"jwt": "valor obtido no login"
}

Exemplo de Resposta:

1
2
3
4
5
6
7
8
9
10
11

{
    "records": [
        {
            "livro": "1",
            "titulo": "Gênesis",
            "testamento": "1",
            "autor": "Moisés",
            "descricao": "Embora o texto não contenha relatos internos de quem foi o autor, a autoria foi tradicionalmente atribuída pela tradição judaico-cristã a Moisés, um profeta e legislador hebraico. Esta tradição é baseada em diversas passagens da Bíblia Hebraica que retratam Moisés 'escrevendo'."
        }
    ]
}

Acesso Negado

Se você recebeu inesperadamente um retorno do tipo “Acesso negado”, provavelmente está faltando o Token de Login ou o seu nível de identificação não é suficiente para a ação. Este instrumento protege a API de ataques maliciosos. Por isso será necessário se cadastrar na API (faça isso aqui) ou melhorar o seu nível de identificação aqui.

Exemplo de ação desvinculada de Tabela

Algumas ações não são vinculadas diretamente a uma Tabela (da camada de persistência). São ações de mais alto nível que, provavelmente, envolve consulta em mais de uma Tabela do banco de dados. Neste caso, a requisição é feita imediatamente no serviço:

https://www.joda.com.br/biblia/rnd_trecho.php

Neste exemplo, um retorno com um trecho da bíblia será obtido. Trata-se de uma ação de alto nível que retorna um trecho pre formatado para ser ‘consumido’ diretamente no site, APP ou Funcionalidade de software.

Veja mais detalhes desta ação: