API do Hi Activity (v1.0)

Endereço base

Todos os endereços referenciados neste documento tem como base a seguinte URL:

https://activity-api.hiplatform.com/1.0/

A API do Activity é servida somente sob HTTPS. Para garantir a privacidade das informações, HTTP não criptografado não é suportado.

Autenticação/Autorização

As requisições para a API do Activity são protegidas utilizando Autenticação básica. Em resumo, a Hi Platform irá fornecer um usuário e uma senha exclusivamente para o uso da API, de forma que todas as requisições realizadas devem fornecer estas credenciais.

Cabeçalhos comuns a todas as operações

As requisições para a API do Activity devem possuir os seguintes cabeçalhos:

Cotas de consumo

O cliente que usar essa API estará sujeito a um limite na quantidade de requisições que poderá enviar em um dado período de tempo. Essa prática é conhecida como Rate Limiting e é utilizada para garantir a qualidade do serviço.

A cada 'X' minutos (variável conforme o escopo solicitado) o cliente tem direito a fazer um determinado número de requisições (também variável conforme o escopo). Passado o tempo especificado, o limite é reiniciado.

O consumo do limite pode variar conforme o escopo e deve ser acompanhado pelos seguintes http headers:

• X-Rate-Limit-Limit: informa o total de requisições permitidas dentro de uma janela de X minutos.
• X-Rate-Limit-Remaining: informa quantas requisições para API ainda são permitidas dentro da janela de X minutos corrente. Se uma requisição for feita após esse valor retornar 0, a API retornará o HTTP status code 429 (Too many connections.).
• X-Rate-Limit-Reset: devolve o número de segundos disponíveis na janela atual.

Escopos de rate limiting

Importante: Certifique-se de checar o escopo de rate limiting no resumo de cada operação.

Paginação

Determinadas operações podem potencialmente retornar muitos registros. Nestes casos os resultados serão sempre paginados e os seguintes parâmetros opcionais são suportados através de query string:

• pageNumber: Número da página desejada. Se esse parâmetro não for passado ou for maior do que a quantidade de páginas disponíveis, será assumido que a busca é da página 1;
• pageSize: Quantidade máxima de registros por página. Deve ser um número entre 10 e 1000. Se esse parâmetro não for passado, será assumido o valor 1000;

Para auxiliar na navegação nos resultados retornados, as operações que requerem paginação devolverão os seguintes cabeçalhos HTTP:

X-Pagination-TotalResult: Total de resultados.
X-Pagination-TotalPages: Total de páginas.
Link: <https://activity-api.hiplatform.com/1.0/...\>; rel="First", 
      <https://activity-api.hiplatform.com/1.0/...\>; rel="Previous", 
      <https://activity-api.hiplatform.com/1.0/...\>; rel="Next", 
      <https://activity-api.hiplatform.com/1.0/...\>; rel="Last"

É importante notar que a existência dos links está sujeita ao contexto atual. Por exemplo: se a página atual for a primeira, então o link Previous não estará disponível.

Importante: Certifique-se de checar a paginação no resumo de cada operação.

Retornos comuns para todas as operações

##### Cabeçalhos

##### Códigos HTTP

##### Corpo

	{
        "status": "...",
        "data:" {
            ...
        },
        "errors": ["..."]
	}

• status: Há três tipos de status possíveis:

  • OK: A requisição foi recebida com sucesso pelo DT.Rest.Api.Activity.
  • NOTVALID: A requisição foi recebida pelo DT.Rest.Api.Activity, mas não passou na etapa de validação. Os detalhes da validação estarão na lista errors.
  • ERROR: Um erro não esperado ocorreu durante a requisição.

• data: Retorno da operação

• errors: Lista com erros sempre que o status não for OK".

Em endpoints com paginação, o conteúdo do campo data muda para conter também dados relacionados ao total de registros e paginação.

	"data": {
		"totalResults": 1,
        "totalPages": 1,
        "pageNumber": 1,
        "items": [
            ...
        ]
	}

• totalResults: Total de registros dessa consulta.
• totalPages: Total de páginas que ocupam todos os registros dessa consulta.
• pageNumber: Qual página está atualmente sendo retornada.
• items: Array com os objetos retornados pela operação.

# Sub-Recursos

Origens

• GET /source (listar sources)

Tipos

• GET /type (listar types)

Categorias

• GET /category (listar category)

Atividades

• GET /activity (listar atividades)

# Listar Origens

##### Resumo

RESPOSTA

##### Cabeçalhos em caso de sucesso

##### Corpo em caso de sucesso

    {
        [
            {
                "id": "...",
                "description": "...",
                "active": "..."
            }
        ]
    }

• id: GUID que representa o identificador da origem.
• description: Descrição.
• active: true/false.

# Listar Tipos

##### Resumo

RESPOSTA

##### Cabeçalhos em caso de sucesso

##### Corpo em caso de sucesso

    {
        [
            {
                "id": "...",
                "description": "...",
                "active": "..."
            }
        ]
    }

• id: GUID que representa o identificador do tipo.
• description: Descrição.
• active: true/false.

# Listar categorias

##### Resumo

REQUISIÇÃO

##### Parâmetros

• sourceId: Identificador da origem.

##### Formato

• O sourceId informado deve ser GUID válido.

RESPOSTA

##### Cabeçalhos em caso de sucesso

##### Corpo em caso de sucesso

    {
        [
            {
                "id": "...",
                "description": "...",
                "active": "..."
            }
        ]
    }

• id: GUID que representa o identificador da categoria.
• description: Descrição.
• active: true/false.

# Listar atividades

##### Resumo

REQUISIÇÃO

##### Parâmetros

• startDate: Data/hora inicial para busca, no formato epoch.
• endDate: Data/hora final para busca, no formato epoch.

##### Parâmetros opcionais

• categoryId: Identificador da categoria. Se houver mais de um, deve ser separado por vírgula.
• sourceId: Identificador da origem. Se houver mais de um, deve ser separado por vírgula.
• typeId: Identificador do tipo. Se houver mais de um, deve ser separado por vírgula.

##### Formato

• O período informado por startDate e endDate deve ser válido.
• O(s) categoryId informado(s) deve(m) ser GUID(s) válido(s).
• O(s) sourceId informado(s) deve(m) ser GUID(s) válido(s).
• O(s) typeId informado(s) deve(m) ser GUID(s) válido(s).

RESPOSTA

##### Cabeçalhos em caso de sucesso

##### Corpo em caso de sucesso

    {
        [
            {
                "id": "...",
                "description": "...",
                "actionDescription": "...",
                "actionId": "...",
                "actionName": "...",
                "categoryDescription": "...",
                "categoryId": "...",        
                "typeDescription": "..",
                "typeId": "...",
                "sourceDescription": "...",
                "sourceId": "...",
                "creationTime": 1,
                "username": "...",
                "userId": "...",
                "details": [
                    {
                        "id": "...",
                        "description": "..."
                    },
                    ...
                ],
                "links": [
                    {
                        "id": "...",
                        "description": "...",
                        "url": "..."
                    },
                    ...
                ]
            }
        ]
    }

• id: GUID que representa o identificador da atividade.
• description: Descrição.
• actionDescription: Descrição da ação associada a essa atividade.
• actionId: ID da ação associada a essa atividade.
• actionName: Nome da ação associada a essa atividade.
• categoryDescription: Descrição da categoria.
• categoryId: GUID que representa o identificador da categoria.
• typeDescription: Descrição do tipo da atividade.
• typeId: GUID que representa o identificador do tipo.
• sourceDescription: Descrição da origem da atividade.
• sourceId: GUID que representa o identificador da origem.
• creationTime: Data de criação, no formato epoch.
• username: Nome do usuário que gerou essa atividade.
• userId: GUID que representa o identificador do usuário que gerou essa atividade.
• details: Lista com detalhes que foram associados a atividade:
  • id: GUID que representa o identificador do detalhe.
  • description: Descrição do detalhe.
• links: Links associados a essa atividade
  • id: GUID que representa o identificador do link.
  • description: Descrição do link.
  • url: URL do link.

Artigos relacionados:

Gestão de usuários de API