...

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. (opcional)

Exemplo de filtros no padrão odata:

...

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'

...

• 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;

...

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 GET, PUT e DELETE

...

JSON deve ser o formato padrão para 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 https://totvs.com/api/fluig/fdn/v1/users/10
{
	_expandables: ["permissions","communities","detailedInformation"],
    id: 10,
    name: "John",
    surname: "Doe",
    age: 25,
    country: "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:

...