...

POST http://totvs.com/api/users/10

{
  name: "",
  age: 20,
  ...
}

POSTPATCH http://totvs.com/api/users/10

{
  name: "Novo nome do usuário"
}

...

POST https://totvs.com/api/users
{
 ...
}

202 Accepted
Location: https://totvs.com/api/users/10

Padrões de cabeçalhos de requisição

A utilização destes cabeçalhos não é obrigatória para todos os endpoints, mas os que os utilizarem devem obedecer as regras descritas abaixo.

Como escolher o método adequado

Abaixo descrevemos algumas situações e o método adequado a ser usado.

GET

• Quero retornar uma lista de usuários;
• Quero retornar o usuário com o id x;
• Quero retornar todas as permissões do usuário x;
• Quero retornar todos os usuário maiores de idade;

PUT

• Quero sobrescrever o usuário atual na base de dados usando os dados informados na requisição;
• Quero alterar o estado do usuário para ativo independente de outras regras;

PATCH

• Quero alterar o estado do usuário para inativo validando uma série de regras no servidor;
• Quero alterar uma propriedade do usuário e para faze-lo o servidor irá alterar também propriedades de outras entidades;
• Quero alterar a data de vencimento de uma conta mas apenas se for nos primeiros 15 dias do mês;

POST

• Quero adicionar um novo usuário;
• Quero executar uma ação ou serie de operações no usuário;
  
  

Padrões de cabeçalhos de requisição

A utilização destes cabeçalhos não é obrigatória para todos os endpoints, mas os que os utilizarem devem obedecer as regras descritas abaixo.

...

Mensagens de sucesso

Mensagens de sucesso devem ser retornadas para todos os códigos http 2xx e devem ter pelo menos o campo data (código http 2xxdevem) devem retornar diretamente a entidade que representa o objeto resultado da operação do endpoint. Ex:

{
GET  data: {}
}http://totvs.com.br/api/users/1

{
  name: "John",
  sobrenome: "Doe"
}

Âncora
ApiSuccessMsgColl ApiSuccessMsgColl

Mensagens de sucesso para coleções

...

{
  data: {
    hasNext: true,
    items: [
      {},
      {},
      ...
    ]
  }
}

Código 4xx versus 5xx

Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.

Erros de negócio ou requisição

São aqueles causados por dados inválidos nas requisições ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatoriamente retornar um código HTTP da família 4xx. Ex:

O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized;

O cliente chamou um endpoint mas mesmo estando autenticado não possui as permissões necessárias para efetuar a operação. Deve retornar o código 403 - Forbidden;

O cliente chamou o endpoint para buscar um usuário (Ex: /users/{id}) mas o usuário não existe. Deve ser retornado o código de erro 404 - Not found;

O cliente chamou o endpoint para efetuar alguma operação mas por alguma regra de negócio a operação não pode ser concluída e não existe um código de erro HTTP apropriado para descrevê-lo. Deve ser retornado o código de erro 400 - Bad Request;

O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço só consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable.

Erros não esperados

...

Além destes campos obrigatórios é possível retornar campos opcionais e para diferenciá-los deve-se usar o prefixo totvs_. Ex.:

{
  totvs_total: 100,
  hasNext: true,
  items: [
    {},
    {},
    ...
  ]
}

Código 4xx versus 5xx

Dividimos os erros em duas categorias: Erros de negócio ou requisição e Erros não esperados.

Erros de negócio ou requisição

São aqueles causados por dados inválidos nas requisições ou intencionalmente lançados do endpoint para o cliente. Todos os erros deste tipo devem obrigatoriamente retornar um código HTTP da família 4xx. Ex:

O cliente chamou um endpoint mas não estava devidamente autenticado. Deve ser retornado o código 401 - Unauthorized;

O cliente chamou um endpoint mas mesmo estando autenticado não possui as permissões necessárias para efetuar a operação. Deve retornar o código 403 - Forbidden;

O cliente chamou o endpoint para buscar um usuário (Ex: /users/{id}) mas o usuário não existe. Deve ser retornado o código de erro 404 - Not found;

O cliente chamou o endpoint para efetuar alguma operação mas por alguma regra de negócio a operação não pode ser concluída e não existe um código de erro HTTP apropriado para descrevê-lo. Deve ser retornado o código de erro 400 - Bad Request;

O cliente chamou o endpoint passando no cabeçalho que aceita como retorno xml (Content-Type: text/xml) mas o serviço só consegue retornar JSON. Deve retornar o erro HTTP 406 - Not Acceptable.

Erros não esperados

São os erros não tratados ou não intencionais. Esse tipo de erro devesempre retornar códigos HTTP da família 5xx. Ex:

O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;

O cliente chamou um endpoint para subir um documento mas não havia espaço em disco no servidor. Deve retornar o código 507 - Insufficiente Storage.

Parâmetros expansíveis

Todos os endpoints devem respeitar e suportar os campos expansíveis. E devem retornar os campos retraídos a menos que especificado na requisição através do parâmetro de url expand.

As entidades de retorno devem obedecer as regras:

Todas as propriedades que representam listas devem vir retraídas por padrão e devem usar a notação de lista vazia (Ex.: [] ).

Todas as propriedades que representam objetos devem vir retraídos e usar a notação de objeto sem propriedades. (Ex.: {} )

Ao retornar uma entidade, todas as suas propriedades que representam um objeto ou coleção devem vir retraídas e a entidade deve conter um campo adicional com o nome _expandables. Esse campo é uma lista com o nome de cada uma das propriedades que podem ser passadas na url para que o endpoint inclua na responta.

Por exemplo, a entidade usuário possui propriedades que apontam para suas permissões, comunidades e detalhes e portanto estas devem estar retraídas:

GET https://totvs.com/api/users/10


{

O cliente chamou um endpoint mas o servidor não pode responder por que estava sobrecarregado. Deve retornar o código 503 - Service Unavailable;

O cliente chamou um endpoint para subir um documento mas não havia espaço em disco no servidor. Deve retornar o código 507 - Insufficiente Storage.

Parâmetros expansíveis

Todos os endpoints devem respeitar e suportar os campos expansíveis. E devem retornar os campos retraídos a menos que especificado na requisição através do parâmetro de url expand.

As entidades de retorno devem obedecer as regras:

Todas as propriedades que representam listas devem vir retraídas por padrão e devem usar a notação de lista vazia (Ex.: [] ).

Todas as propriedades que representam objetos devem vir retraídos e usar a notação de objeto sem propriedades. (Ex.: {} )

Ao retornar uma entidade, todas as suas propriedades que representam um objeto ou coleção devem vir retraídas e a entidade deve conter um campo adicional com o nome _expandables. Esse campo é uma lista com o nome de cada uma das propriedades que podem ser passadas na url para que o endpoint inclua na responta.

Por exemplo, a entidade usuário possui propriedades que apontam para suas permissões, comunidades e detalhes e portanto estas devem estar retraídas:

GET https://totvs.com/api/users/10


{
    data: {
        _expandables: ["permissions", "detailedInformation"]
        id: 10
        name_expandables: ["permissions", "detailedInformation"]
        id: 10
        name: "Usuário"
        age: 25
        permissions: []
        communities: [
            {
                _expandables: ["permissions"],
                name: "Vendas",
                photoUrl: "https://totvs.com/communities/1/photo",
                permissions: {}
            },
            {
                _expandables: ["permissions"],
                name: "Outra comunidade",
                photoUrl: "https://totvs.com/communities/2/photo",
                permissions: {}
            }
        ]
        detailedInformation: { }
    }
}

Caso o cliente queira expandir as propriedades, ele deve então fazer uma requisição informando o parâmetro expand na url e passando como valor uma lista separada por virgula (,) dos campos exatamente como descritos no campo _expandables.

...

GET https://totvs.com/api/users/10?expand=communities

{
    data: {
        _expandables: ["permissions", "detailedInformation"]
        id: 10
        name: "Usuário"
        age: 25
        permissions: []
        communities: [
            {
                _expandables: ["permissions"],
                name: "Vendas",
                photoUrl: "https://totvs.com/communities/1/photo",
                permissions: {}
            },
            {
                _expandables: ["permissions"],
                name: "Outra comunidade",
                photoUrl: "https://totvs.com/communities/2/photo",
                permissions: {}
            }
        ]
        detailedInformation: { }
    }
}

Note que as propriedades do objeto expandido devem vir retraídas por padrão. O cliente pode solicitar que as propriedades dos objetos sejam expandidas separando as sub-propriedades com ponto (.). Usando o exemplo acima, o usuário gostaria de expandir as permissões das comunidades da entidade usuário:

...

GET https://totvs.com/api/users/10?expand=communities.permissions

{
    data: {
        _expandables: ["permissions", "detailedInformation"]
        id: 10
        name: "Usuário"
        age: 25
        permissions: []
        communities: [{
            name: "Vendas",
            photoUrl: "https://totvs.com/communities/1/photo",
            permissions: {
                isAdmin: true,
                canView: true
            }
        }, {
            name: "Outra comunidade",
            photoUrl: "https://totvs.com/communities/2/photo",
            permissions: {
                isAdmin: true,
                canView: true
            }
        }]
        detailedInformation: { }

    }
}
}

...