NAV Navbar
REST

Introdução

Esta documentação sempre refletirá a última versão estável da API da Rekko. Uma recomendação consiste em três principais componentes:

  1. Itens
  2. Usuários
  3. Interações item-usuário

Assumimos então que há um catálogo de itens que estão disponíveis para usuários. Usuários podem interagir com itens das seguintes maneiras:

Além de uma chave primária (identificador único) os itens e usuários possuem diversos outros atributos. Estes atributos são analisados pelo recomendador para futuramente melhorar as recomendações fornecidas. Além disso, você pode utilizar os atributos para filtrar ou impulsionar recomendações de alguns itens em específico. O conjunto de atributos fornecidos é gerenciado pelo usuário da API. Os endpoints da API podem retornar recomendações de itens ou de usuários.

Iniciando com a API da Rekko

A primeira coisa a ser feita para iniciar o uso da Rekko é obter a sua chave secreta da API. Para obter sua chave secreta da API crie sua conta na Rekko caso você ainda não possua uma.

Uma vez que você tenha em mãos a sua chave da API você já pode integrar a sua plataforma a Rekko.

Como integrar

A integração é feita em três etapas:

  1. Envio dos dados de usuários e itens do seu catálogo para a Rekko
  2. Envio das interações entre itens e usuários para a Rekko
  3. Obtendo recomendações da Rekko

Recomendações geralmente são exibidas para usuários em websites, aplicativos móveis ou campanhas de e-mail ou push.

A Rekko permite que você configure quais dados serão enviados para o motor de recomendações, de forma que você pode personalizar o que é ou não utilizado nos cálculos. Quanto mais informações forem enviadas, maiores serão as taxas de conversão pois o motor conseguirá entender melhor o perfil de comportamento dos clientes. Você pode entender sobre os tipos dos dados suportados pela API da Rekko nesta seção

Enviando os dados para Rekko

Dados de usuários e de itens são parte das informações necessárias para se criar uma recomendação, é através destes dados que o nosso motor entende e constrói e armazena o modelo dos seus dados. É muito importante que após a população inicial dos dados, haja uma constante atualização dos dados de novos itens e novos usuários. Para manter os dados atualizados, você deve efetuar uma requisição ADD com os novos dados

Enviado dados de usuário

Um usuário Mônica Sousa é enviado a Rekko utilizando a query a seguir:

POST /beta/add HTTP/1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json 

Body:
{
  "company": "Rekko",
  "database": "rekko_db1",
  "table": "user", 
  "values": {
    "primaryKey": "1",
    "name":"Mônica Sousa",
    "isActive":true,
    "address":{
        "street": “Avenida São Paulo, 398”,
        "state": “Bahia”,
        "city": “Salvador”,
    },
  }
}

Onde company é o nome da sua empresa

Database é o banco de dados

Table é a tabela do banco onde os dados serão inseridos

Values são os atributos do usuário

Enviando dados de um item

Para enviar os dados de um item é muito similar

Para enviar um item Sabão em Pó utiliza-se a mesma query utilizada anteriormente, alterando apenas as informações de database, table e values.

POST /beta/add HTTP/1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json 

Body:
{
  "company": "Rekko",
  "database": "rekko_db1",
  "table": "item", 
  "values": {
    "primaryKey": "139",
    "name":"Sabão em Pó",
    "isActive":true,
    "price": 9.9
}

Envio das interações entre itens e usuários

Supondo a compra de um item Sabão em Pó pelo usuário Mônica Sousa

POST /beta/add HTTP 1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json

Body:
{
  "company": "Rekko",
  "database": "rekko_db1",
  "table": "purchased", 
  "values": {
    "primaryKey": "1",
    "name":"Mônica Sousa",
  }
}

Iterações entre itens e usuários são as informações mais importantes para o algoritmo de recomendação da Rekko. Existem diversos tipos de interações no sistema e você pode entender melhor cada uma delas na nossa seção sobre tipos de interações. Nos exemplos abaixo iremos exibir a utilização de duas delas: comprar um item e clicar em um item.

Caso a usuário Mônica clique em um livro

POST /beta/add HTTP 1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json

Body:
{
  "company": "Rekko",
  "database": "rekko_db1",
  "table": "clicked", 
  "values": {
    "primaryKey": "35",
    "name":"Monica",
  }
}

Alterando informações de usuários e itens

Caso o preço de um produto sofra alterações, a requisição pode ser feita da seguinte maneira

POST /beta/update HTTP 1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json

Body:
{
  "company": "Rekko",
  "database": "rekko_db1",
  "table": "item", 
  "values": {
    "price" : 19.9
  },
  "where": {
    "column" : "sku",
    "op" : "=",
    "value" : 30491
  }
}

Caso alguma informação seja alterada, como o preço deu um determinado item no catálogo, é importante que você atualize as informações presentes na Rekko. As únicas tabelas que podem sofrer modificações são USER e ITEM.

Para alterar uma informação em um conjunto de itens

POST /beta/update HTTP 1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json

Body:
{
  "company": "Rekko",
  "database": "rekko_db1",
  "table": "item", 
  "values": {
    "discount" : 10
  },
  "where": {
    "column" : "price"
    "op" : ">",
    "value": 1000
  }
}

Adicionando colunas nas tabelas de usuário e itens

A API do Rekko possui suporte para a adição e remoção de colunas para as tabelas de usuários e itens através das requisições de alter.

Para alterar as colunas presentes na tabela de usuário

POST /beta/alter HTTP 1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json

Body:
{
  "company": "Rekko",
  "database": "rekko_db1",
  "table": "user", 
  "add": {
    "birthDate" : "Date"
  },
  "remove": {
    "address", "photo"
  }
}

Você pode fazer requisições contendo somente o atributo add, somente remove ou ambos como a requisição exibida ao lado

Removendo dados

Uma requisição de Drop pode ser feita enviando apenas as informações de qual a tabela que será removida

POST /beta/drop HTTP 1.0
Host: https://a9jsfgylxc.execute-api.sa-east-1.amazonaws.com/api
Content-type: application/json

Body:
{
  "company": "Rekko", 
  "database": "rekko_db1", 
  "table_type": "likes"
}

Para a remoção completa de uma tabela de dados da Rekko, você pode executar uma requisição Drop para a API.

Interações

Um usuário pode interagir com um item de diversas maneiras e cada uma delas é interpretada de maneira diferente pelo motor de recomendações. É extremamente importante que as iterações sejam enviadas para a Rekko pois elas aumentam a qualidade das recomendações geradas.

Interação Significado Tabela associada
Clicar em um item O usuário abriu a página específica de um item. CLICKED
Comprar um item O usuário finalizou a compra de um item. PURCHASED
Ver um item O usuário visualizou um item da loja. VIEWED
Avaliar um item O usuário publicou ou realizou uma avaliação de um item. REVIEWED
Adicionar ao carrinho O usuário adicionou um item ao carrinho. CARTADDED
Marcou como favorito O usuário adicionou um item a sua lista de favoritos. BOOKMARKED
Curtiu um item O usuário curtiu um item. LIKED
Escreveu um comentário O usuário publicou na página do item um comentário. COMMENTED

As tabelas suportadas e suas utilizações

Tabela Utilização
USER Armazena as informações dos usuários da sua plataforma
ITEM Armazena as informações seu catálogo de produtos
PURCHASED Armazena as informações de itens comprados na sua plataforma
VIEWED Armazena as informações de itens que foram visualizados pelos usuários, isto é, exibidos de alguma maneira na página
RATED Armazena as informações de itens que foram avaliados por usuários da sua plataforma
CARTADDED Armazena as informações de itens que foram adicionados ao carrinho
BOOKMARKED Armazena as informações de itens que foram adicionados para serem visualizados mais tarde
LIKED Armazena as informações de itens que foram curtidos
COMMENTED Armazena as informações dos comentários feitos em itens
CLICKED Armazena as informações de itens que foram clicados

Operações disponíveis

Em requisições que possuem o atributo where é necessário especificar a operação que será realizada. A tabela abaixo contém as informações das operações de comparação suportadas pela API da Rekko

Tipo Descrição
= {"column":"price", "value":1000, "OP":"="}. Verdadeiro se o atributo price for igual a value.
< {"column":"price", "value":1000, "OP":"<"}. Verdadeiro se o atributo price for menor que value.
<= {"column":"price", "value":1000, "OP":"<="}. Verdadeiro se o atributo price for menor ou igual a value.
> {"column":"price", "value":1000, "OP":">"}. Verdadeiro se o atributo price for maior que value.
>= {"column":"price", "value":1000, "OP":">="}. Verdadeiro se o atributo price for maior ou igual a value.
! {"column":"isActive", "OP":"!"}. Verdadeiro se o atributo isActive for falso.

Códigos de erro

Tipo Descrição
2xx Sucesso
4xx Erro do cliente
5xx Erro do servidor

Tipos de dados

A API da Rekko suporta uma série de tipos de dados que podem ser usados para especificar colunas na hora de criar uma tabela para os seus dados. Na tabela abaixo você encontra uma lista com todos os dados suportados:

Tipo Descrição
Number Qualquer número (inteiro ou de ponto flutuante)
String String UTF-8
Boolean Verdadeiro ou falso
Date Valor representando uma data. O número em milisegundos desde a época UNIX (1 de Janeiro de 1970 00:00:00 UTC).
PrimaryKey Valor representando a chave primária de uma tabela.
URL Valor contendo uma URL