API de Ensalamento
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.
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:
ClassesManagement
- {host}/classes: Retorna todas as classes cadastradas na base de dados.
- {host}/classes/{sourcedId}: Retorna os dados referentes a uma classe especifica. {sourcedId} representa o GUID único da class na base de dados.
- {host}/classes/{classSourcedId}/teachers: Retorna todos os Users do type teachers vinculados a determinada Class no fluxo de Ensalamento. {classSourcedId} representa o GUID único da class na base de dados.
- {host}/classes/{classSourcedId}/students: Retorna todos os Users do type students vinculados a determinada Class no fluxo de Ensalamento. {classSourcedId} representa o GUID único da class na base de dados.
CoursesManagement
- {host}/courses: Retorna todos os courses cadastrados na base de dados.
- {host}/courses/{sourcedId}: Retorna os dados referentes a um course especifico. {sourcedId} representa o GUID único do course na base de dados.
- {host}/courses/{courseSourcedId}/classes: Retorna todas as Classes vinculadas a determinado Course no fluxo de Ensalamento. {courseSourcedId} representa o GUID único do Course na base de dados.
OrgsManagement
- {host}/orgs: Retorna todas as Orgs cadastradas na base de dados.
- {host}/orgs/{sourcedId}: Retorna os dados referente a uma Org especifica. {sourcedId} representa o GUID único da Org na base de dados.
SchoolsManagement
- {host}/schools : Retorna todas as Orgs do type school cadastradas na base de dados.
- {host}/schools/{sourcedId}: Retorna os dados referentes a uma Org do type school especifico. {sourcedId} representa o GUID único da Org do type school na base de dados.
- {host}/schools/{schoolSSourcedId}/classes: Retorna todas as Classes vinculadas a determinada Org do type school no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da Org do type school na base de dados.
- {host}/schools/{schoolSSourcedId}/students : Retorna todos os Users do type students vinculados a determinada Org do type school no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da Org do type school na base de dados.
- {host}/schools/{schoolSSourcedId}/teachers : Retorna todos os Users do type teachers vinculados a determinada Org do type school no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da Org do type school na base de dados.
- {host}/schools/{schoolSSourcedId}/courses : Retorna todos os Courses vinculados a determinada Org do type school no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da Org do type school na base de dados.
- {host}/schools/{schoolSSourcedId}/classes/{classSourcedId}/students: Retorna todos os Users do type students vinculados a determinada Class que está vinculadas a uma determina Org do type school no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da Org do type school na base de dados. {classSourcedId} representa o GUID único da class na base de dados.
- {host}/schools/{schoolSSourcedId}/classes/{classSourcedId}/teachers: Retorna todos os Users do type teachers vinculados a determinada Class que está vinculadas a uma determina Org do type school no fluxo de Ensalamento. {schoolSourcedId} representa o GUID único da Org do type school na base de dados. {classSourcedId} representa o GUID único da class na base de dados.
UsersManagement
- {host}/users: Retorna todos os Users cadastrados na base de dados.
- {host}/users/{sourcedId}: Retorna os dados referentes a um User especifico. {sourcedId} representa o GUID único do User na base de dados.
- {host}/users/{userSourcedId}/classes: Retorna todas as Classes vinculadas a determinado User no fluxo de Ensalamento. {userSourcedId} representa o GUID único do User na base de dados.
StudentsManagement
- {host}/students: Retorna todos os Users do type student cadastrados na base de dados.
- {host}/students/{sourcedId}: Retorna os dados referentes a um User do type student especifico. {sourcedId} representa o GUID único do User do type student na base de dados.
- {host}/students/{studentSourcedId}/classes: Retorna todas as Classes vinculadas a determinado User do type student no fluxo de Ensalamento. {studentSourcedId} representa o GUID único do User do type student na base de dados.
TeachersManagement
- {host}/teachers: Retorna todos os Users do type teacher cadastrados na base de dados.
- {host}/teachers/{sourcedId}: Retorna os dados referentes a um User do type teacher especifico. {sourcedId} representa o GUID único do User do type teacher na base de dados.
- {host}/teachers/{teacherSourcedId}/classes: Retorna todas as Classes vinculadas a determinado User do type teacher no fluxo de Ensalamento. {teacherSourcedId} representa o GUID único do User do type teacher na base de dados.
AcademicSessionManagement
- {host}/AcademicSessions : Retorna todos os AcademicSessions cadastrados na base de dados.
- {host}/AcademicSessions/{sourcedId}: Retorna os dados referentes a um AcademicSession especifico. {sourcedId} representa o GUID único do AcademicSession na base de dados.
Utilizando a API
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.
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.
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 essas requisições sejam executadas. A janela de tempo para grandes requisições é entre 22h e as 6h.
Para obter informações completas recomendamos a utilização dos EndPoint sem Filtros. Desta forma será obtido 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 especifica.
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]
Referências
IMS Global - OneRoster
https://www.imsglobal.org/oneroster-v11-final-specification#_Toc480451981