O que é possível fazer com a API Edools

Com a nossa API você será capaz de integrar qualquer sistema externo ao Edools, realizar migrações de dados de plataformas antigas de maneira simples e direta, e construir aplicativos para estender uma funcionalidade existente ou até mesmo criar novas funcionalidades com sua lógica própria. Através da API você tem toda a flexibilidade necessária para adaptar o Edools às suas regras de negócio, tendo uma plataforma de ensino online que se encaixe perfeitamente às suas necessidades.

Nosso modelo de dados foi todo pensado para lhe permitir a flexibilidade necessária para se adaptar ao seu domínio. Basicamente, a API tem 3 pilares com objetivos específicos:

• Gestão de Equipe: gerenciar seus colaboradores, identificar todas as ações dentro da plataforma, definir grupos com papéis específicos.
• Gestão de Conteúdo: gerenciar sua biblioteca com trilhas, cursos, aulas e mídias, criar produtos para comercializar online.
• Gestão de Alunos: gerenciar seus alunos, identificar como estão progredindo ao consumirem seu conteúdo, definir gatilhos para engajar seus alunos no ambiente virtual.

Nos próximos artigos iremos detalhar cada secão da API, passando por todos os pontos específicos de cada área, com exemplos reais de utilização em diferentes segmentos de mercado.

Endpoint

A URL base onde se encontra a raiz da nossa API é:

https://sua-escola.myedools.com/api

Todo o acesso à nossa API é feito usando o protocolo HTTPS, sem exceção, com dados criptografados para maior segurança.

Versionamento

Por padrão, todas as requisições para a API que não especificarem um versão serão redirecionadas para a última versão da API, que no momento é a v1. Por esse motivo, nós recomendamos que sempre explicite a versão que você deseja, mesmo se estiver usando a última versão. Dessa forma, quando futuras atualizações ocorrerem, sua aplicação estará requisitando a versão correta. Basta informar a versão no header da requisição:

Accept: application/vnd.edools.core.v1+json

Autenticação e Autoriazção

Ao fazer um requisição para a API, ela irá passar por um processo de autenticação e autorização. A primeira verifica se as credencias que você tem são válidas para ter acesso à API. A segunda verifica se tais credenciais tem permissão para acessar o dado, ou conjunto de dados, solicitado.

O modelo responsável por gerenciar essa lógica na API é o ApiKey. Cada ApiKey possui um token e um secret, que são gerados automaticamente na sua criação, e combinados formam o que chamamos de credentials. Além deles, a ApiKey possui um owner e um realm. O owner define o User ou App a quem pertence àquela chave. Já o realm, indica qual o domínio da API a chave terá acesso, que no geral são sempre Organization ou School.

No momento o único formato aceito para se autenticar na API é passando o seguinte header na chamada:

Authorization: Token token="CREDENTIALS"

Dessa forma, a API irá identificar quem está acessando, e verificar se ele tem permissão para isso. Vamos analisar a seguinte requisição para o endpoint de produtos:

$ curl -H 'Authorization: Token token="CREDENTIALS" https://sua-escola.myedools.com/api/school_products

Após o passo de autenticação, a API irá realizar um verificação de Autorização. Por exemplo, se o domínio o qual a chave tem acesso for uma organização, esse endpoint irá retornar todos os produtos de todas as escolas da organização. Porém, se o domínio permitido for uma escola específica, será retornado apenas os produtos da escola em questão.

Agora, analisando o caso a requisição seja por um produto específico:

$ curl -H 'Authorization: Token token="CREDENTIALS"' https://sua-escola.myedools.com/api/school_products/100

Da mesma forma, se a chave tiver acesso à organização e o produto específico pertencer à organização, o passo de autorização irá retornar OK, retornando os detalhes do produto. Porém, se a chave for de uma escola e o produto não pertencer àquela escola, a autorização irá falhar e retornar um 401.

Quando uma requisição falhar por ter fracassado no passo de autenticação, você irá receber uma resposta HTTP com código 401 e mensagem Bad credentials. Caso passe pelo passo de autenticação, mas falhe na autorização, a resposta irá com o mesmo código 401, porém com a mensagem Resource not authorized.

Durante a descrição de cada recurso, explicamos as condições necessárias para o passo de autorização passar e em quais condições ele pode não autorizar.

Representação de dados

A API tem em seu cerne o fato de ser uma API JSON, ou seja, JSON é único formato suportado. Em seguido iremos expor os principais padrões adotados que suportam o esquema da API.

Representação de Listas

Ao requisitar uma lista de um determinado produto, a resposta inclui um subconjunto dos atributos daquele recurso. Isso é o que chamamos de representação resumida do recurso. O principal motivo é o fato de alguns atributos serem computacionalmente caros de serem fornecidos em grandes quantidades. Então, visando a performance como um todo, esse formato reduzido exclui esses atributos. Para obtê-los, basta requisitar a representação detalhada.

Por exemplo, ao realizar um requisição para obter a lista de produtos, você receberá a representação resumida dos produtos.

Representação Detalhada

No caso de requisitar um objeto específico de um recurso, a resposta irá retornar por padrão a representação detalhada desse recurso. Tal formato inclui todos os atributos daquele recurso. A única observação é que alguns atributos podem ser escondidos por motivos de permissões.

Ao descrevermos cada método da API, será fornecida os atributos da representação detalhada dos recursos.

Campos vazios

Campos vazios, ou nulos, são retornados como null ao invés de serem omitidos.

Timestamps

Todas as timestamps são retornadas no seguinte formato: YYYY-MM-DDTHH:MM:SSZ

Parâmetros

Muitos métodos da API aceitam parâmetros opcionais para filtros e outras funções. Nas requisições GET basta adicionar os parâmetros como query string.

No exemplo a seguir, iremos pegar todos os produtos que estão publicados:

$ curl -i "https://sua-escola.myedools.com/api/school_products?published=true"

Para os métodos HTTP POST, PATCH, PUT e DELETE, os parâmetros devem ser inseridos no body da requisição.

Verbos HTTP

Onde é possível, a API usa os verbos HTTP apropriados para cada ação:

• HEAD: Pode ser requisitado em qualquer recurso apenas para obter a informação HTTP no header da resposta.
• GET: Listagem ou informação detalhada.
• POST: Criação de recursos ou realização de ações customizadas.
• PATCH: Usado para atualizar dados parciais de recursos.
• PUT: Usado para substituir recursos.
• DELETE: Deletar recursos.

Erros

A API segue a definição padrão do protocolo HTTP, obedecendo aos códigos de resposta. Alguns erros comuns são:

• Enviar um JSON inválido resulta em um Bad Request.

HTTP/1.1 400 Bad Request
Content-Length: 35

{"message":"Problems parsing JSON"}

• Enviar valores com tipagem incorreta também resulta em um Bad Request.

HTTP/1.1 400 Bad Request
Content-Length: 40

{"message":"Body should be a JSON Hash"}

• Em requests para criar/atualizar objetos, enviar atributos inválidos resultam em Unprocessable Entity

HTTP/1.1 422 Unprocessable Entity
Content-Length: 157

{
    "message": "Validation Failed",
    "errors": [
        {
           "resource": "SchoolProduct",
           "field": "title",
           "code": "missing_field"
        }
    ]
}

Respostas de código 422 sempre retornam metadados que indicam o motivo pelo qual falhou a requisição, fique atento. Os recursos que possuem validações específicas estão documentados na sua descrição.

Paginação

Requisições que retornam múltiplos items são paginadas por padrão para retornar apenas 10 items. Você pode especificar as páginas através do parâmetro page.

Para alguns recursos você também pode especificar o tamanho da página até o limite de 100 itens, usando o parâmetro per_page.

Observe que por razões técnicas, nem todos os recursos aceitam o parâmetro per_page.

$ curl 'https://sua-escola.myedools.com/api/school_products?page=2&per_page=100'

A paginação é 1-based, ou seja, a primeira página é a 1. Ao omitir o parâmetro page, sempre será retornado a primeira página.

Chave de acesso

Para obter sua chave de acesso à API, basta mandar um email para o nosso suporte.

Ajuda

Caso esteja enfrentando alguma dificuldade que não está documentada, entre em contato com o nosso suporte no email [email protected] usando a tag [API] no assunto.

Por favor, faça uma boa descrição do problema que está enfrentando e onde precisa de ajuda.

Nosso time de suporte possui desenvolvedores experientes e preparados para auxiliar no que for necessário para que seu uso de nossa API ocorra sem problemas.