Conector de dados#

O conector de dados preenche um site NAMES LEGAL a partir de dados que já existem noutro local, sem código do lado do proprietário do site. O proprietário liga uma fonte na sua consola (Integrações → Importar os meus dados), associa colunas a campos por arrastar e largar, executa um teste e lança. As fontes podem ser ficheiros ou uma API — a sua.

Esta página destina-se a programadores de aplicações que pretendem ser uma fonte: o que o NAMES LEGAL espera da sua API, e como tornar a ligação automática.

Como o conector lê a sua API#

O proprietário do site introduz:

• o endereço da sua API,
• um modo de autenticação e o respetivo segredo,
• opcionalmente, onde está a lista na sua resposta (data.items).

O NAMES LEGAL chama então a sua API através de HTTPS com GET, segue a paginação e transforma cada objeto numa linha. Os objetos aninhados são achatados (author.name), as listas de valores simples são unidas com vírgulas.

Autenticação#

Os segredos são armazenados encriptados e nunca voltam a ser mostrados na consola. Forneça aos proprietários de sites uma chave só de leitura, limitada ao conteúdo publicado: o conector apenas lê.

Localizar a lista#

Se não for indicado nenhum caminho, o conector utiliza, por ordem: a matriz items, depois a primeira matriz de objetos encontrada na resposta. Uma matriz JSON simples também funciona.

Paginação#

Qualquer um destes é seguido automaticamente, até 200 páginas:

• um cabeçalho HTTP Link: <…>; rel="next";
• um URL da página seguinte no corpo: next, next_url, next_page_url, links.next, meta.next, pagination.next;
• um cursor no corpo: next_cursor, meta.next_cursor, pagination.next_cursor — devolvido como ?cursor=.

Para parar, devolva uma lista vazia ou nenhuma ligação seguinte.

Limites#

• 5000 linhas por conjunto de dados e sincronização.
• 10 MB por resposta, 15 segundos por pedido.
• Os endereços têm de ser públicos: endereços privados e de rede local são recusados, incluindo redirecionamentos. Num redirecionamento para outro anfitrião, a chave não é reencaminhada.

O formato de feed NAMES LEGAL#

Exponha os seus dados neste formato e o proprietário do site não tem nada para associar: cada coleção torna-se num conjunto de dados já ligado à secção correspondente do site.

1. Um índice#

GET https://app.example.com/api/names-legal/

{
  "names_legal_feed": 1,
  "collections": {
    "team": "https://app.example.com/api/names-legal/team/",
    "services": "https://app.example.com/api/names-legal/programmes/",
    "blog": "https://app.example.com/api/names-legal/news/"
  }
}

Os nomes das coleções são as chaves de secção listadas na referência de campos abaixo (team, services, blog, events, faq, jobs…). Os URLs podem ser relativos ao índice.

2. Uma lista por coleção#

{
  "items": [
    {
      "id": "T-104",
      "first_name": "Awa",
      "last_name": "Diop",
      "position": "Mathematics teacher",
      "short_bio": "Twelve years of teaching.",
      "profile_image": "https://app.example.com/media/staff/104.jpg",
      "email": "a.diop@example.com"
    }
  ],
  "next": null
}

Regras:

• id — um identificador estável, diferente em cada linha. É através dele que uma linha editada atualiza a mesma ficha em vez de criar uma nova.
• Os nomes dos campos são os da referência de campos.
• Os campos traduzidos têm uma chave por idioma: title_fr, title_en, description_de… Uma chave sem sufixo vai para o idioma predefinido do site.
• As imagens e os ficheiros são URLs públicos. São transferidos uma vez e voltam a ser transferidos apenas quando o URL muda. São aceites ligações de partilha do Google Drive e do Dropbox.
• As categorias são indicadas pelo nome ("category": "Bachelor"); as categorias em falta são criadas.
• As datas estão em ISO 8601. Os booleanos são true/false.
• Os campos de texto formatado aceitam HTML; este é limpo (sem scripts, sem manipuladores de eventos). O texto simples transforma-se em parágrafos.
• Devolva apenas o que pode ser publicado: rascunhos e dados privados não devem aparecer no feed.

Manter o site atualizado#

O proprietário do site escolhe, por secção:

Também é escolhido o que acontece quando uma ficha foi alterada em ambos os lados (os dados da fonte prevalecem, o site prevalece, ou é pedida confirmação), e quando uma linha desaparece do feed (eliminar no site, ocultar, ou manter). Uma sincronização que removesse uma grande parte de uma secção é interrompida e pede confirmação primeiro.

Escrever de volta na aplicação de origem ("o meu site → a minha fonte") ainda não está disponível: o conector apenas lê.

Referência de campos#

Gerada a partir da própria plataforma; está sempre atualizada. Os campos obrigatórios têm de estar presentes em cada linha (no caso de um campo traduzido, em pelo menos um idioma).

Tamanho da equipe team

Serviços services

Projetos projects

Blogue / notícias blog

Eventos events

Perguntas frequentes faq

Vagas de emprego jobs

Recursos resources

Publicações publications

Depoimentos testimonials

Habilidades skills

Números-chave stats