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.
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.
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.
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.
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.
- Conhecimentos sobre API Rest.
- Requisitar ClientId e ClientSecret (Obrigatório para uso da API).
- Conhecimento sobre o Padrão OneRoster.
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.
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"
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.
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).
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'
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.
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.
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.
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"
}
}
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]
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.
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.
IMS Global - OneRoster
https://www.imsglobal.org/oneroster-v11-final-specification#_Toc480451981