O que mudou em relação a versão anterior?

Índice

...

• Entidade apresentada no plural e uso correto do parâmetro na url.
  • https://totvs.com/api/fdn/v1/users/{id}

• Ações sobre entidades no caminho da url e como parâmetro da url.
  • https://totvs.com/api/bpm/v1/workflows/{id}?action=execute
  • https://totvs.com/api/bpm/v1/workflows/{id}/send

• Relacionando entidades diretamente no caminho
  
  • https://totvs.com/api/fdn/v1/users/{alias}/communities
  • https://totvs.com/api/social/v1/communities/{id}/users

• URL com suporte a campos expansíveis
  
  • https://totvs.com/api/fdn/v1/users/{alias}?expand=prop1.subprop,prop2

• Ordenando e paginando coleções
  • https://totvs.com/api/fdn/v1/users?order=name,-age&page=2&pageSize=20
• URL com Query Param e nome composto:
  • https://totvs.com/api/fdn/v1/users/?firstName=joao

Exemplo de URLS NÃO amigáveis e que deve ser evitadas

• Redundância na definição da url
  • https://totvs.com/api/communty/listCommunities

• Ordenação especificada na url
  • https://totvs.com/api/communty/listCommunitiesWithRelevance

• Verbos definidos na url ao invés de usar o verbo HTTP e falta de pluralização no substantivo
  
  • https://totvs.com/api/correlationquestion/create
  • https://totvs.com/api/user/create
  • https://totvs.com/api/user/delete

• Identificador da entidade definido como parâmetro e não como caminho (na url)
  • https://totvs.com/api/document/permissions?documentId={id}
    
    

...

Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio, criar um novo grupo de endpoints implica em preocupações como versionamento, disponibilidade e documentação. Usamos como base a estrutura "{protocolo}://{host}/{api}/{agrupador}/{dominio}/{versao}/{recurso}". Ex: https://fluig.totvs.com/api/ecm/security/v1/users. A partir deste ponto deve-se considerar como regra básica a complexidade necessária para descobrir estes endpoints, ou seja, o agrupamento deve facilitar e não complicar a descoberta dos serviços.

...

...

openapi: 3.0.1
info:
  title: Estrutura de Url para API's
  description: 'Consideramos uma API o agrupamento de endpoints que façam parte da mesma unidade de negócio. Usamos como base a estrutura "{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}"'
  version: '1.0'
externalDocs:
  url: 'http://tdn.totvs.com/display/INT/Guia+de+implementacao+das+APIs+TOTVS'
servers:
  - url: '{protocolo}://{host}/{api}/{produto}/{agrupador}/{dominio}/{versao}/{recurso}'
    variables:
      protocolo:
        default: https
        enum:
          - http
          - https
      host:
        default: host
      api:
        default: api
      produto:
        default: produto
      agrupador:
        default: agrupador
      dominio:
        default: dominio
      versao:
        default: versao
      recurso:
        default: recurso
paths: {}
components: {}

...

Todos os endpoints de coleção devem suportar ordenação. A definição de como a lista deve ser ordenada é definida no parâmetro de urlquery order respeitando as seguintes regras:

• O parâmetro de query da urlURL deve ter o nome order;
• O valor do parâmetro order é uma lista de campos, separada por virgula (,) opcionalmente precedida pelo sinal de subtração (-);
  
• A lista deve respeitar a ordem dos campos como descrito na url para fazer a ordenação;
• Campos precedidos por um sinal de subtração (-) devem ser ordenados de forma decrescente;
• Campos que omitirem o sinal (subtração) devem ser ordenados de forma crescente.

...

As coleções podem suportar filtro e devedevem usar as técnicas abaixo de acordo com a complexidade exigida pela função:

...

Filtros simples devem usar parâmetros de query no formato propriedade=filtrovalor e as propriedades suportadas e , bem como a forma como elas serão interpretadas, devem estar listadas na documentação do endpoint. Ex:

GET https://totvs.com.br/api/fluig/fdn/v1/users?name=john&surname=doe

Filtros complexos

Filtros complexos e que forneçam uma linguagem de filtro devem seguir o padrão definido para os filtros no documento ODATA na versão 4. (opcional)

Exemplo de filtros no padrão odata:

Opcionalmente, em endpoints que tenham estrutura com entidades aninhadas, a propriedade usada para filtrar os resultados deve usar o formato propriedade_pai.propriedade_filho.

Não há limite para os níveis que se pode referenciar, mas deve-se levar em consideração o quão complexa pode ser a implementação. Quando houver limitação quanto a quantidade de níveis referenciados, importante documentar na API.

Exemplo de uso do filtro com propriedades aninhadas:

GET https://totvs.com.br/api/fluig/fdn/v1/users?communities.name="Vendas"

No exemplo acima, serão retornados todos os usuários (users) cuja propriedade name (que está contida na propriedade communities da entidade users) seja igual a "Vendas".

Filtros complexos (opcional)

Filtros complexos e que forneçam uma linguagem de filtro devem seguir o padrão definido para os filtros no documento ODATA na versão 4.

Exemplo de filtros no padrão odata:

Filtros de data Modificação (opcional)

Opcionalmente, a api pode disponibilizar o filtro especial "datemodified" para retornar registros alterados a partir de uma determinada data.

O valor desse filtro deve seguir o definido em Formatos de data.

Exemplo Ex:

GET https://totvs.com.br/api/fluig/fdn/v1/users?datemodified='2018-01-01'

...

GET https://totvs.com.br/api/fluig/fdn/v1/users?$filter=datemodified ge '2018-01-01' and datemodified le '2018-01-31'

Paginação

Todos os endpoints de coleção devem suportar paginação. A definição de como a coleção deve ser paginada é definida pelos parâmetros de url page e pageSize respeitando as seguintes regras:

...

• O parâmetro page é opcional e na sua ausência deve ser considerado o valor 1;

• O valor do parâmetro pageSize deve ser um valor numérico (maior que zero) representando o total de registros retornados na consulta;

...

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

{
  name: "John",
  age: 2025,
  ...
}

PATCH http://totvs.com/api/fluig/fdn/v1/users/10

[
  { "op": "replace", "path": "/name", "value": "Bob" }
]

...

Métodos DELETE, GET, HEAD e OPTIONS não deve ser utilizado corpo na mensagem e sim utilizar query string .

Em métodos POST evitar a utilização de path param e utilizar corpo na mensagem a fim de manter as boas práticas de desenvolvimento.

Campo chave (id) dos verbos Campo chave (id) dos verbos GET, PUT e DELETE

O valor passado como parâmetro de URL (path param) dos verbos GET, PUT e DELETE deve representar o identificador único do registro dentro do contexto do endpoint. Ou seja, baseado no valor (id) passado, o provedor de informação deve ser capaz de identificar de forma inequívoca o registro dentro da base de dados. Caso necessário, é possível concatenar diversos campos para compor o identificador.

...

JSON deve ser o formato padrão para mensagens mensagens de resposta. Apenas nos casos onde se justificar, outro tipo de mídia pode ser usado. Por exemplo, numa API que retorne uma imagem ou um documento PDF. 

Tipos de dados JSON

Os tipos de dados e a notação para os campos da mensagem JSON deve seguir os padrões descritos no documento ECMA-404.

...

GET http://totvs.com.br/api/fluig/fdn/v1/users/110

{
    _expandables: ["permissions","communities","detailedInformation"],
    id: 10,
    name: "John",
    surname: "Doe",
    age: 25,
    country: "US"
}

Opcionalmente, o atributo _messages pode ser incluído no objeto retornado para fornecer alguma informação complementar ao processamento realizado (mensagens de aviso, de negócio, etc.). O formato do objeto de mensagem segue o padrão anteriormente descrito, para mensagens de erro.

GET http://totvs.com.br/api/fluig/fdn/v1/users/110

{
    _expandables: ["permissions","communities","detailedInformation"],
    id: 10,
    name: "John",
    surname: "Doe",
    age: 25,
    country: "US"
    _messages: [{
	    code: "INFO",
        message: "ThisEsta isé anuma informativemensagem messageinformativa",
        detailedMessage: "SomeMais detailsdetalhes aboutsobre thisesta informativemensagem messagepodem canser be found here!vistos aqui."
    }]
}

Âncora
ApiSuccessMsgColl ApiSuccessMsgColl

Mensagens de sucesso para coleções

...

{
  hasNext: true,
  items: [
    {},
    {},
    ...
  ],
  _messages: [{
    code: "INFO",
    message: "someUma infomensagem messageinformativa.",
    detailedMessage: "detailsDetalhes aboutrelativos thea info messagemensagem."
  }]
}

A estrutura acima é a mínima esperada para respostas de coleção. Entretanto, pode-se retornar mais campos se for necessário desde que a estrutura básica se mantenha. Por exemplo:

...

GET http://totvs.com.br/api/fluig/fdn/v1/users/10

{
    _expandables: ["Permissions"permissions","communities","detailedInformation"],
  name   id: 10,
    name: "John",
    surname: "Doe",
    age: 1825,
    country: "US"
}

Caso os únicos campos interessantes para o cliente sejam o "name" e "age" ele pode reduzir a quantidade de dados usando o parâmetro fields. Ex:

GET http://totvs.com.br/api/fluig/fdn/v1/users/10?fields=name,age

{
  name   name: "John",
    age: 1825
}

...

GET https://totvs.com/api/fluig/fdn/v1/users/10


{
        _expandables: ["permissions", "communities", "detailedInformation"],
        id: 10,
    name: "John",
   name surname: "UsuárioDoe",
    age: 25,
   age country: 25"US"
}

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/fluig/fdn/v1/users/10?expand=communities

{
        _expandables: ["permissions", "communities","detailedInformation"]  # refere-se aos atributos do objeto pai (1o nível)
   ,
     id: 10,
        name: "UsuárioJohn",
    surname: "Doe",
    age: 25,
    country: "US",
    communities: [{
        _expandables: ["permissions"],   {
                _expandables: ["Permissions"],   # # refere-se ao atributo permissions destede objeto-filhocommunities (2o nivel)
                name: "Vendas",
                photoUrl: "https://totvs.com/communities/1/photo"
            },
            {
                _expandables: ["permissions"],  # refere-se ao atributo permissions destede objeto-filhocommunities
                name: "Outra comunidade",
                photoUrl: "https:photoUrl: "https://totvs.com/communities/2/photo"
            }
        ]
      
}

Note que as propriedades do objeto expandido não são retornadas 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/fluig/fdn/v1/users/10?expand=communities.permissions

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

Requisições Assíncronas

...

Ao realizar um POST, PUT ou DELETE em um recurso que executa seu processamento de maneira assíncrona, o mesmo DEVE retornar o código 202 Accepted, com cabeçalho location apontando para um recurso temporário que permita o acompanhamento do status da requisição.

Informações
title Atenção
A implementação do modelo assíncrono não é obrigatório. A opção por este modelo deve basear no tempo e recurso necessário para o processamento de uma requisição.

Processando

Ao realizar o GET no recurso temporário, enquanto ainda estiver sendo processado, o mesmo DEVE retornar o código 200 e um JSON com a propriedade status definida como “pending”. Esse retorno PODE, e é uma boa prática, retornar a propriedade progress, informando o percentual de conclusão da operação solicitada.

...

Para cancelar a execução do processamento, quando permitido, o client deve executar DELETE no recurso temporário.

Finalizada – Erro

Ao acessar o recurso temporário que finalizou seu processamento com erros, retorna o erro adequado, conforme definido em Mensagens de Erro  e Código 4xx versus 5xx

Finalizada – Sucesso

Ao acessar o recurso temporário que finalizou seu processamento com sucesso, o mesmo DEVE retornar o código 303 (See Other) com o cabeçalho Location, apontando para endereço do real recurso criado.

A deleção do recurso temporário não é obrigatória e PODE ser feita através de DELETE do client, ou através do próprio server, após um tempo determinado para expirá-lo. Nesse segundo caso, ao tentar acessá-lo DEVE retornar 410 (Gone).

Padrão HATEOAS

...

Esse estilo de arquitetura permite usar links no conteúdo da resposta para que o cliente possa navegar dinamicamente para o recurso apropriado. Isso é conceitualmente o mesmo que um usuário da Web navegando pelas páginas e clicando nos hiperlinks apropriados para atingir uma meta final.

O padrão HATEOAS deve ser utilizado no retorno de entidades relacionadas a principal e que não são parte do recurso principal. Ex.

Bloco de código
language js
GET https://totvs.com/api/fluig/fdn/v1/users/10 { _expandables: ["permissions","communities","detailedInformation"], "id" : 10, name: "John", "name" surname: "UsuárioDoe", age: 25, "age" country: 25, "links": [ { "rel": "communities", "href": "/fdn/v1/communities/5" }, { "rel": "permissions", "href": "/fdn/v1/permissions/30" } ] } "US", "links": [ { "rel": "communities", "href": "/fdn/v1/communities/5" }, { "rel": "permissions", "href": "/fdn/v1/permissions/30" } ] }

Tipos de Conteúdo

O formato padrão e recomendado de tipo de conteúdo, ou "Content-Type", a ser trafegado via APIs é "application/json".

Em alguns casos pode existir a necessidade de utilizar "application/xml" , por ex: quando é exigido por legislação.  Nessa situação, as mesmas regras definidas nos tópicos anteriores continuam valendo, visto que estas estão relacionadas ao schema. (Se possível, evitar esse uso e sempre priorizar o JSON)

Outro cenário é o download e upload de arquivos binários: Não utilizamos os tipos "multipart/xxxx", e sim os mais específicos ao tipo do arquivo.
Exemplos:

• "image/png" para o download ou upload de um arquivo com extensão ".png".

• "application/pdf" para o download ou upload de um arquivo com extensão ".pdf".

Clique aqui para lista completa dos tipos permitidos

Versionamento

As APIs devem ser versionadas sempre que alguma alteração quebrar o contrato entre o usuário e a plataforma, a versão deve estar presente na URI e deve estar no forma v{major.minor}.
A versão major indica uma grande versão da API, ou seja, a API mudou significativamente em seu formato e comportamento.
A versão minor indica uma alteração que pode quebrar o código do cliente.
Por exemplo:

...

O numero da versão indica para o cliente quando alguma alteração pode "quebrar" o código escrito por ele. Deve-se tomar um cuidado especial no processo de versionamento para que o cliente esteja ciente dessas alterações e a frequência com que elas acontecem usando algum tipo de release notes ou documentação.

Alterações que devem gerar uma nova versão "major"

...

• URIs foram removidas ou renomeadas;
• Foram removidos campos do retorno de um endpoint;
• Foi removido o suporte a um método do endpoint (GET, PUT, POST, etc);
• Um novo parâmetro obrigatório é exigido para o correto funcionamento do endpoint;
• Um novo endpoint foi adicionado a API.

Alterações que NÃO devem gerar uma nova versão "major"

...

• Um novo formato de retorno é suportado pelo endpoint;
• Novas propriedades são retornadas na entidade de retorno do endpoint;
• Novos parâmetros opcionais podem ser passados para o endpoint.

...