API REST

Uma API REST expõe os dados de uma aplicação como recursos, como /orders ou /orders/42, e permite que os clientes ajam sobre eles com os métodos HTTP padrão. REST (Representational State Transfer) é um estilo arquitetural, e não um padrão formal, então as APIs reais o seguem em graus diferentes. As ideias centrais são URLs orientadas a recursos, uso coerente dos métodos HTTP e dos status codes e requisições stateless (sem estado): cada requisição leva tudo o que o servidor precisa, inclusive a autenticação.

Exemplo

Requisição	Significado	Sucesso típico
GET /orders?status=open	Listar pedidos em aberto	200 OK
GET /orders/42	Ler um pedido	200 OK
POST /orders	Criar um pedido	201 Created + header Location
PUT /orders/42	Substituir o pedido	200 OK ou 204 No Content
PATCH /orders/42	Alterar alguns campos	200 OK
DELETE /orders/42	Excluir o pedido	204 No Content

Um teste com REST Assured 5:

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.equalTo;

given()
    .baseUri("https://api.example.com")
    .header("Accept", "application/json")
.when()
    .get("/orders/42")
.then()
    .statusCode(200)
    .body("id", equalTo(42))
    .body("status", equalTo("open"));

O que testar em uma API REST

• Status codes para o sucesso e para cada caminho de falha: autenticação ausente, papel errado, corpo inválido, id inexistente, conflitos.
• Corpo e schema da resposta: nomes de campos, tipos, campos obrigatórios e se campos sensíveis não estão expostos.
• Headers: Content-Type, Location depois de uma criação e headers de cache e CORS quando forem relevantes.
• Semântica dos métodos: GET não tem efeitos colaterais, PUT e DELETE são idempotentes.
• Autorização no nível do objeto: o usuário A não pode conseguir ler um /orders/{id} que pertence ao usuário B.
• Paginação, filtros e ordenação, incluindo páginas vazias e a última página.

Como ela se diferencia de outros estilos de API

O GraphQL normalmente expõe um único endpoint, no qual o cliente descreve os dados que quer, e muitas vezes retorna 200 mesmo quando parte da query falhou, então os testes precisam inspecionar o campo errors. O SOAP usa envelopes XML e um contrato formal em WSDL. O gRPC usa HTTP/2 e Protocol Buffers. Uma suíte de testes REST depende muito do próprio HTTP, e é por isso que os fundamentos de HTTP são tão importantes para quem testa APIs.