API de Ensalamento

O que é?

Esta API foi desenvolvida utilizando como base o padrão OneRoster da IMSGlobal. A API tem como base a semântica do padrão, assim como a estrutura dos objetos. Porém retornamos apenas os valores obrigatórios da documentação da IMSGlobal.

Será demonstrado neste guia de implantação quais são os EndPoints implementados, as regras de utilização adotadas e as modificações feitas para as entidades de Retorno.

Projeto modelo

Para facilitar a integração, foi criado o projeto modelo que pode ser utilizado inicialmente para testar a configuração com a FTD e como referência para implementar a solução final com o parceiro. Para mais detalhes clica aqui.

Entidades do Modelo OneRoster

Para o Ensalamento no padrão OneRoster temos as seguintes entidades:

Org - Representa uma organização ao qual o fluxo de Ensalamento pertence. Seguindo o padrão esta entidade pode ser dos Tipos: department, district, local, national, school, state. O fluxo atual da API Org esta retornando apenas o type school.

User - Representa o usuário cadastrado na base de dados. Seguindo o padrão esta entidade pode ter uma das seguintes Roles: administrator, aide, guardian, parent, proctor, relative, student,  teacher. Para o fluxo atual da API as Roles retornadas são: Loja, Editorial Admin, School Admin, Student, Teacher.

Class - Representa uma turma que está vinculada ao fluxo de Ensalamento.

Course - Representa um curso que está vinculado ao fluxo de Ensalamento.

AcademicSession - Representa o período letivo vinculado ao Curso.

EndPoints do Modelo OneRoster 

O Padrão organiza a sua API em diferentes blocos representando suas entidades e relacionamentos a fim de dar clareza a usabilidade do mesmo.

Os Blocos da API são:

   ClassesManagement: Onde se encontram os EndPoints referentes a Classes.

   CoursesManagement: Onde se encontram os EndPoints referentes a Courses.

   OrgsManagement: Onde se encontram os EndPoints referentes a Orgs.

   SchoolsManagement: School é um type de Org. Neste Bloco se encontram os EndPoints que são específicos para o Type School.

   UsersManagement: Onde se encontram os EndPoints referentes a Users.

   StudentsManagement: Student é um type de User. Neste Bloco se encontram os EndPoints que são específicos para o Type Student.

   TeachersManagement: Teacher é um type de User. Neste Bloco se encontram os EndPoints que são específicos para o Type Teachers.

   AcademicSessionManagement: Onde se encontram os EndPoints referentes a Users.

EndPoints organizados por bloco:

Segue endereços (host) do OneRoster:
Homologação: https://ftd-apim-hml.azure-api.net/ims/oneroster/v1p1
Produção: https://ftd-apim-prd.azure-api.net/ims/oneroster/v1p1 

ClassesManagement

         - {host}/classes: Retorna todas as turmas cadastradas na base de dados.

         - {host}/classes/{sourcedId}: Retorna os dados referentes a uma turma específica. {sourcedId} representa o GUID único da turma na base de dados.

         - {host}/classes/{classSourcedId}/teachers: Retorna todos os professores vinculados a uma determinada turma no fluxo de ensalamento. {classSourcedId} representa o GUID único da turma na base de dados.

         - {host}/classes/{classSourcedId}/students: Retorna todos os alunos que estão vinculados a uma determinada turma no fluxo de ensalamento. {classSourcedId} representa o GUID único da turma na base de dados.

 

    CoursesManagement

        - {host}/courses: Retorna todos os cursos cadastrados na base de dados.

        - {host}/courses/{sourcedId}: Retorna os dados referentes a um curso específico. {sourcedId} representa o GUID único de um curso na base de dados.

        - {host}/courses/{courseSourcedId}/classes: Retorna todas as turmas vinculadas a um determinado curso no fluxo de ensalamento. {courseSourcedId} representa o GUID único de um curso na base de dados.

   

    OrgsManagement

       - {host}/orgs: Retorna todas as Orgs cadastradas na base de dados.

       - {host}/orgs/{sourcedId}: retorna os dados referentes a uma Org específica. {sourcedId} representa o GUID único da Org na base de dados.

   

    SchoolsManagement

       - {host}/schools : Retorna todas as entidade do tipo escola cadastradas na base de dados.

       - {host}/schools/{sourcedId}: Retorna os dados referentes a uma escola específica. {sourcedId} representa o GUID único da escola na base de dados.

       - {host}/schools/{schoolSSourcedId}/classes: Retorna todas as Classes vinculadas a uma determinada Org do tipo escola no fluxo de ensalamento. {schoolSourcedId} representa o GUID único da Org do tipo escola na base de dados.

       - {host}/schools/{schoolSSourcedId}/students : Retorna todos os usuários do tipo aluno vinculados a uma determinada escola no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da organização do tipo escola na base de dados.

       - {host}/schools/{schoolSSourcedId}/teachers : Retorna todos os usuários do tipo professor vinculados a uma determinada escola no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da organização do tipo escola na base de dados.

       - {host}/schools/{schoolSSourcedId}/courses : Retorna todos os cursos vinculados a uma determinada escola no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da organização do tipo escola na base de dados.

       - {host}/schools/{schoolSSourcedId}/classes/{classSourcedId}/students: retorna todos os usuários do tipo aluno vinculados a uma determinada turma que está vinculada a uma determinada organização do tipo escola no fluxo de ensalamento. {schoolSourcedId} representa o GUID único da organização do tipo escola e {classSourcedId} representa o GUID único da turma na base de dados.

       - {host}/schools/{schoolSSourcedId}/classes/{classSourcedId}/teachers: retorna todos os usuários do tipo professor vinculados a determinada turma que está vinculada a determinada organização do tipo escola no fluxo de ensalamento. {schoolSourcedId} representa o GUID único da organização do tipo escola e {classSourcedId} representa o GUID único da turma na base de dados.

   

    UsersManagement

       - {host}/users: Retorna todos os usuários cadastrados na base de dados.

       - {host}/users/{sourcedId}: Retorna os dados referentes a um usuário específico. {sourcedId} representa o GUID único do usuário na base de dados.

       - {host}/users/{userSourcedId}/classes: Retorna todas as turmas vinculadas a um determinado usuário no fluxo de ensalamento. {userSourcedId} representa o GUID único do usuário na base de dados.

 

    StudentsManagement

       - {host}/students: Retorna todos os usuários do tipo aluno cadastrados na base de dados.

       - {host}/students/{sourcedId}: Retorna os dados referentes a um usuário do tipo aluno especifico. {sourcedId} representa o GUID único do usuário do tipo aluno na base de dados.

       - {host}/students/{studentSourcedId}/classes: Retorna todas as turmas vinculadas a um determinado usuário do tipo aluno no fluxo de ensalamento. {studentSourcedId} representa o GUID único do usuário do tipo aluno na base de dados.

    TeachersManagement

       - {host}/teachers: Retorna todos os usuários do tipo professor cadastrados na base de dados.

       - {host}/teachers/{sourcedId}: Retorna os dados referentes a um usuário do tipo professor. {sourcedId} representa o GUID único do usuário do tipo professor na base de dados.

       - {host}/teachers/{teacherSourcedId}/classes: Retorna todas as turmas vinculadas a determinado usuário do tipo professor no fluxo de ensalamento. {teacherSourcedId} representa o GUID único do usuário tipo professor na base de dados.

    AcademicSessionManagement

       - {host}/AcademicSessions: Retorna todas as sessões acadêmicas na base de dados.

       - {host}/AcademicSessions/{sourcedId}: Retorna os dados referentes a uma sessão acadêmica. {sourcedId} representa o GUID único da sessão acadêmica na base de dados.

    EnrollmentsManagement

       - {host}/enrollments: Retorna todas as matrículas na base de dados.

       - {host}/enrollments/{sourcedId}: Retorna as matrículas em escolas e turmas de um determinado usuário. {sourcedId} representa o GUID único de um usuário na base de dados.

Como aplicar?

Pré-requisitos

 - Conhecimentos sobre API Rest.

 - Requisitar ClientId e ClientSecret (Obrigatório para uso da API).

 - Conhecimento sobre o Padrão OneRoster.

 

Primeiros passos

Para utilização da API é necessário obter um access_token. Para obter esse access_token é necessário solicitar a criação de um User Sistêmico e de posse do ClientId e ClientSecret obter o token. Solicitar host para utilizar a API.

No tópico Downloads, você encontrará as especificações técnicas da API (Swagger) e um arquivo json que pode ser importado no Postman para realizar as chamadas à API. Você também pode consultar as especificações da API aqui.

Ano Escolar

As escolas possuem os anos escolas (Academic Sessions), que podem ser obtidos pelo endpoint

/schools/{:schoolSourcedId}/terms

Obtendo o guid do ano escolar, pode-se utiliza-lo no filtro para obter as "Classes" apenas do ano desejado, por exemplo:

/schools/{:schoolSourcedId}/classes?filter=terms='sourcedIdAcademicSession'

Consulte mais detalhes no sobre como utiizar o filter no tópico "Fluxo de Filtering"

Fluxos de paginação

Seguindo o padrão todas as requisições tem como limite de retorno 100 registros, retornando no Header do response na propriedade Link as URL de paginação Next, Last, First e Prev.

 

Fluxo de Sorting 

Seguindo o padrão é possível ordenar os dados requisitados passando como parâmetro as propriedades sort e orderBy. Na propriedade sort é possível informar qualquer field que exista no modelo da entidade requisitada. Na propriedade orderBy é possível informar asc (para ordenação ascendente) ou desc (para ordenação decrescente).

 

Fluxo de Filtering 

Seguindo o padrão é possível aplicar filtros para todos os fields existentes no modelo da entidade requisitada. O filtering é possível informando o parâmetro filter.

Por exemplo:

- Para filtrar os usuários "Administradores" da Org "99d156f2-16c4-11ea-8c78-bbc55ddf4924"
/ims/oneroster/v1p1/users?&filter=org='99d156f2-16c4-11ea-8c78-bbc55ddf4924'+AND+role='Administrator'

- Para trazer os usuário que foram editados desde 12/09/2023 as 10:50

/ims/oneroster/v1p1/users?&filter=dateLastModified>='2023-09-12T10:50:00.000'

 

Fluxo de Field Selection 

Seguindo o padrão é possível determinar quais os fields serão retornados na requisição. Na propriedade field é possível passar qualquer field que exista no modelo da entidade requisitada.

 

Fluxo de cache 

Todas as requisições passam por um cache. A TTL (Time to Live) do cache é de 1 hora para a API. A API proporciona a possibilidade de ignorar o cache enviando no Header da requisição o parâmetro disableCache = true.

 

Utilização e Recomendações 

A API possui limitação de horário para requisições de grande volume, existindo uma janela de tempo para que tais requisições sejam executadas. A janela de tempo para grandes requisições é entre 22h e 6h.

Para obter informações completas, recomendamos a utilização dos EndPoint sem Filtros. Assim, será obtida a informação completa de ensalamento.

Caso já tenha sido realizado uma rotina de importação utilizando a API, você pode obter novas informações utilizando o filtering com a propriedade dateLastModified (data da última modificação do registro) contida em todas as entidades no modelo de dados. Com essa propriedade, pode-se obter apenas os registros modificados a partir de uma data específica.

 

Massa de Teste para a API 

Para testar a API foi criada uma Escola de teste com todo o fluxo de Ensalamento. Seguem os dados da Escola e o retorno (em Json) para das chamadas dos EndPoint da API.

 

Org (type School): Escola Primavera

sourcedId: 608d2b10-358c-11eb-b3f9-dbddbbc85f4b

 

{host}/schools/{sourcedId}

{

    "org": {

        "sourcedId": "608d2b10-358c-11eb-b3f9-dbddbbc85f4b",

        "name": "Escola Primavera",

        "status": "active",

        "identifier": "PRIMAINFANTIL",

        "type": "school",

        "dateLastModified": "2020-12-03"

    }

}

Modelo de Dados

Class.Type:

    sourcedId:  GUID

    status: enum [active | tobedeleted]

    dateLastModified: string (date-time)

    title: string

    classCode: string

    school: GUIDRef.Type

 

Course.Type

    sourcedId: GUID

    status: enum [active | tobedeleted]

    dateLastModified: string (date-time)

    title: string

    courseCode: string

    org: GUIDRef.Type

 

Org.Type

    sourcedId: GUID

    status: enum [active | tobedeleted]

    dateLastModified: string (date-time)

    name: string

    type: school

    identifier: string

 

User.type

    sourcedId: GUID

    status: enum [active | tobedeleted]

    dateLastModified: string (date-time)

    username: string

    givenName: string

    familyName: string

    orgs: array [GUIDRef.Type]

 

GUIDRef.Type

    href: string (uri)

    sourcedId: GUID

    type: enum [class | course | org | student | teacher | user]

Tenants e Escopos

Para adquirir um token para as chamadas ao OneRoster é necessário fazer um POST (x-www-form-urlencoded) para o endereço:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token (conferir o tenant a ser enviado na lista abaixo)


Passando os seguintes dados:

grant_type: client_credentials

client_id: seu-clientId-do-ambiente

client_secret: seu-secret-correspondente-ao-clientId-utilizado

scope: conforme ambiente, com os valores listados abaixo


Lista de tenant por ambiente:

DEV - https://ionicadev.onmicrosoft.com

HML - https://ionicahml.onmicrosoft.com

PRD - https://ionicaprd.onmicrosoft.com


Lista de escopos a serem utilizados por ambiente:

DEV - https://ionicadev.onmicrosoft.com/oneroster-api/.default

HML - https://ionicahml.onmicrosoft.com/oneroster-api/.default

PRD - https://ionicaprd.onmicrosoft.com/oneroster-api/.default

Não deixe de conferir a collection do postman na sessão Downloads desta página.

Modelo OneRoster

Por padrão nossas APIs respondem no modelo OneRoster internacional, onde a base do modelo são os cursos, porém caso seja necessário, é possivel configura-lo para responder em um modelo mais adequado ao brasileiro, baseado em turmas. Consulte nossa equipe para verificar o melhor modelo para sua integração.