Endpoint
Um endpoint é a URL onde seu serviço pode ser acessado por uma aplicação cliente.
Por exemplo, você tem um site que armazena um cadastro de fotos; um endpoint poderia ser:
http://meusite.com/api/V1/fotos/lista
ou então
http://meusite.com/api/V1/fotos/adicionar
E cada endpoint teria o método HTTP conveniente. No primeiro caso seria um GET onde você está "pegando" uma lista de fotos.
No segundo, um POST, onde você está "inserindo" fotos.
Schema
Schema é um vocabulário de dados estruturados que define entidades, ações e relacionamentos na Internet (páginas da Web, emails, etc.).
De maneira resumida, um esquema é um conjunto de regras que representam e validam a estrutura e o formato dos dados. Em alto nível, os esquemas fornecem uma definição abstrata de um objeto do mundo real (como uma pessoa) e destacam quais dados devem ser incluídos em cada instância desse objeto (como nome, sobrenome, aniversário e assim por diante).
Além de descrever a estrutura dos dados, os schemas aplicam restrições e expectativas aos dados para que possam ser validados conforme se movem entre os sistemas. As definições padrão permitem que os dados sejam interpretados de forma consistente, independentemente da origem, e removem a necessidade de tradução entre aplicativos.
Tipos de Parâmetros nas requisições REST
REST (Representational State Transfer) é como um guia de boas práticas.
É um modelo de arquitetura de software que define uma série de requisitos para que as APIs sejam desenvolvidas.
Há várias maneiras de fazer requisições HTTP do front end para o back end usando REST. Os principais métodos são: GET, POST, PUT, PATCH e DELETE, sendo que alguns podem receber parâmetros na URL ou não.
- GET: Através dessa requisição, nós pedimos a representação (retorno de dados) de um recurso;
- POST: Normalmente usado sem passagem de parâmetro. É utilizado quando queremos criar um recurso;
- PUT: Normalmente usado com parâmetro. Use para editar o recurso;
- PATCH: Serve para atualizar partes de um recurso, e não o recurso todo;
- DELETE: Exclui o recurso especificado.
Para exemplificar os tipos, vamos usar os verbos GET e POST nas requisições.
Tipos
Existem três tipos de parâmetros - Dois deles comumente utilizados no método GET e um no método POST:
- Query Params (GET)
- Route Params (GET)
- Body Params (POST e PUT)
✅ Query Params
Recebe os dados da requisição como parâmetro na URL, filtrando as consultas na aplicação. Por exemplo, pode conter um ou mais parâmetros:
http://minhaapi.com/banks?name=meubanco
No exemplo acima, é acessado o recurso (ou rota) banks, filtrando por name, e para inserir parâmetros utiliza-se ? após a rota e adiciona-se a propriedade e valor: name=meubanco. Portanto, o parâmetro fica ?name=meubanco.
http://minhaapi.com/movies?name=transformers&action=megan,peter
Neste segundo exemplo é acessada a API de filmes, pesquisando por name e actors.
Sempre que for passar mais de um parâmetro, podemos colocar & para separar os parâmetros.
✅ Route Params
Recebe os dados da requisição na rota. É a melhor maneira para buscar algo específico, deletar ou atualizar usando o identificador único. Por exemplo:
https://api.github.com/users/123
Nesse exemplo acima, busca-se o usuário do GitHub cujo id é 123.
✅ Body Params
Recebe os dados da requisição no corpo da requisição, em um objeto JSON. Sempre utilizado em requisições cujo método seja POST.
{
"name": "Maria", "age": 18, "email": "[email protected]"
}
No exemplo acima, é feita a requisição para salvar os dados no banco de dados.
Dica
O método PUT também recebe Route Params informando qual recurso vai ser modificado e recebe o Body Params com os valores que serão alterados. A diferença básica, em poucas palavras, o método POST cria um novo recurso e o PUT altera um recurso existente, por isso primeiro ele recebe um Route Params, para localizar o recurso no back end e alterá-lo com os dados enviados via Body Params.