...

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

...

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:

...