Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1708 lines (1250 sloc) 51.1 KB
FORMAT: 1A
HOST: https://partner.opened.com
# OpenEd Partner API
OpenEd is the leading educational resource catalog, with over a million videos, games, assessments, homework, and lesson plans. It is the only site completely focused on aligning educational resources to standards. The **OpenEd Partner API** returns resources for any query with the most effective resources first. Information on efficacy is at: https://assessments.opened.com/resource-effectiveness/
The **OpenEd Partner API** lets you use the capabilities of the OpenEd engine to find resources and provide information about educational standards (Common Core and otherwise) inside your own apps and websites.
All API access is over HTTPS, and accessed from the https://partner.opened.com host. All data is sent and received as JSON.
Our public instance allows partners to make 30k requests every 30 days. Please contact us to discuss a higher rate limit.
All API calls require an OpenEd Access Token. Please write to us at api@opened.com to receive a Client ID and Secret which will allow you to generate an Access Token.
## Feedback and Support
* If you find errors or problems with this documentation, please open a [GitHub issue](https://github.com/openedinc/openedapi/issues/new) with details and information to reproduce the problem. Please note that the GitHub issue database is open to the public, so do not put sensitive information there.
* If you have questions about using this API or about use cases not described here, please feel free to contact us at api@opened.com.
* For response time, uptime status and other metrics on the OpenEd Partner API, please visit http://status.opened.com.
# Requesting Credentials
Email us at api@opened.com to request access to the Opened Partner API and to receive a Client ID and Secret.
# User Guide
For a comprehensive guide to integrating the OpenEd API into your application, <a href='http://assessments.opened.com/api/' target='_blank'>start here.</a>
# Group Accounts
## Access Token [/1/oauth/get_token]
### Getting your Access Token [POST]
To use the OpenEd API you will first need to create an account to receive your ACCESS_TOKEN. Your ACCESS_TOKEN will be sent in the header
of all subsequent API requests.
get_token does a find or create to return a token. If you wish to create a student account, you must add role='student'. This is case sensitive.
Teacher roles are created by default.
###Configuring your Header
Once you have received the token, note that your header needs to have the word "Bearer" in it. For example, in Ruby, it would say:
headers = {
:content_type => 'application/json',
:authorization => 'Bearer TOKEN'
}
+ Request (application/json; charset=utf-8)
+ Attributes
+ client_id (required, string) - your opened client id
+ secret (required, string) - your opened secret
+ username (required, string) - chosen by you and will serve as the username of your account.
+ role (optional, string) - teacher or student. default value is teacher.
+ Response 200 (application/json; charset=utf-8)
{
"access_token": "TOKEN",
"expires_in": 7200
}
+ Response 400
{
"error": "Email has already been taken"
}
# Group User
## Search for a User [/1/users/search{?username}]
### Search [GET]
You can get a user object by email or username.
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Parameters
+ username: `testuser` (required, string) - The username or email of the user.
+ Response 200
{
"user":{
"id":16372,
"first_name":"New Student",
"last_name":"1",
"full_name": "New Student 1",
"email": "user_email",
"role": "student",
"username":"student2",
"school_nces_id":"41322"
}
}
## Create a User [/1/users]
### Create [POST]
You can create other accounts to be used later. These accounts must be created with an email and password. You can also specify role as 'teacher' or 'student'. By default, a teacher user will be created.
+ Request (application/json; charset=utf-8)
+ Attributes
+ email: email (string, required)
+ username: username (string, optional)
+ first_name: user first name (string, optional)
+ last_name: user last name (string, optional)
+ password: user_password (string, required)
+ role: teacher or student (string, optional)
+ promo: promo code (string, optional)
+ school_nces_id: NCES_ID (string, optional)
+ client_id: yourclientid (string, required)
+ Headers
Authorization: Bearer TOKEN
+ Body
{
"email": "testuser@test.com",
"first_name": "test",
"last_name": "user",
"password": "password",
"role": "teacher",
"username": "testusername",
"client_id": your_client_id
}
+ Response 200 (application/json; charset=utf-8)
{
"user":{
"id":16372,
"first_name":"New Student",
"last_name":"1",
"full_name": "New Student 1",
"email": "user_email",
"role": "teacher",
"username":"student2"
}
}
+ Response 400
{
"error": "error message"
}
## Update a User [/1/users/{id}]
### Update [PUT]
You can update an existing user account by passing the user id.
+ Parameters
+ id: `34607` (required, number) the existing user id
+ Request (application/json; charset=utf-8)
+ Attributes
+ first_name: `test first name` (string, optional) - user first name (string, optional)
+ last_name: `test last name` (string, optional) - user last name
+ school_nces_id: `1` (string, optional) - NCES_ID
+ Headers
Authorization: Bearer TOKEN
+ Body
{
"first_name": "test",
"last_name": "user",
"school_nces_id": "1"
}
+ Response 200 (application/json; charset=utf-8)
{
"user":{
"id":16372,
"first_name":"New Student",
"last_name":"1",
"full_name": "New Student 1",
"email": "user_email",
"role": "teacher",
"username":"student2"
}
}
# Group Resources
## Search Resources [/1/resources.json/{?descriptive,limit,offset,standard_group,category,standard,area,subject,grades_range,grade_group,publisher,resource_type,contribution_name,license,schema_org,effectiveness,standard_ids,featured,embeddable,case_identifiers}]
### Search [GET]
Search OpenEd's resource catalog using one or more of the parameters below.
<h3>Resource URL Parameters</h3>
<p>The resource search response will return two helper links which link to the resource details page on OpenEd.
These links are commonly used to iframe an OpenEd resource into a third party site.</p>
<code>
<b>share_url</b>: This url is formatted for teachers and optimized for an iframe.<br/>
<b>student_url</b>: This url is formatted for students and optimized for an iframe.
</code>
Additional parameters can be appened to these urls in order to customize the users experience.
Below is a list of parameters you can use.
<table>
<tr>
<th>Parameter</th>
<th>Values</th>
<th>Description</th>
</tr>
<tr>
<td>`simplifiedView`</td><td>true | false</td><td>This parameter removes header/footer on OpenEd page and optimizes for iframe.</td>
</tr>
<tr>
<td>`student_view`</td><td>true | false</td><td>This parameter removes teacher messaging and actions on OpenEd page.</td>
</tr>
<tr>
<td>`oauth_access_token`</td><td>{ACCESS_TOKEN}</td><td>This is the access token returned from the <a href="http://docs.opened.apiary.io/#reference/accounts/access-token/getting-your-access-token">`get_token`</a> API call. You will need to login each student by passing their username in the <a href="http://docs.opened.apiary.io/#reference/accounts/access-token/getting-your-access-token">`get_token`</a> API call. By then adding their ACCESS_TOKEN to the resource url, they will be automatically logged into OpenEd and resource usage data can be tracked. This is extremely valuable to track your students usage of resources for future recommendations.</td>
</tr>
<tr>
<td>hideRelatedResources</td><td>true | false</td><td>This will hide the related resource list on the right side of the resource details pages.</td>
</tr>
</table>
+ Parameters
+ descriptive: `World War II` (optional, string) - Perform full text search.
+ limit: `10` (optional, number) - Number of resources to return, maximum of 50.
+ offset: `0` (optional, number) - Pagination offset. Should be a multiple of limit.
+ standard_group: `2` (optional, number) - returns resources aligned to specified standards.
+ grade_group: `46` (optional, number) - returns resources aligned to specified grade group.
+ category: `12` (optional, number) - returns resources aligned to specified category.
+ standard: `K.G.2` (optional, string) - returns resources aligned to specified standard.
+ standard_ids: `20276,20277` (optional, array[int]) - returns resources aligned to specific standard.
+ area: `11` (optional, number) - returns resources aligned to specified area.
+ subject: `110` (optional, number) - returns resources aligned to specified subject.
+ grades_range: `K-5` (optional, string) - restricts search to specified grade range. Can be specified as a single grade.
+ publisher: `BrightStorm` (optional, array[string]) - returns resources from the publisher(s) by publisher title(s). Can be specified as single entry, comma-seprated list of titles or a URL-formatted array.
+ resource_type: `video` (optional, array[string]) - returns resources of a specific resource type. Possible types are: "video", "game", "assessment", "homework", "question", "audio", "other", "lesson plan"(lesson plan should be sent with underscore between lesson and plan). Can be specified as single entry, comma-seprated list of types or a URL-formatted array.
+ contribution_name: `LearningRegistry` (optional, string) - the place where the resource was contributed from. Not neccessarily the publisher.
+ featured: `true` (optional, boolean) - returns only resources featured by our opened curators
+ license: `free, premium, paid, all` (optional, string) - the resource license type
+ schema_org: `false` (optional, boolean) - if set to true returns metadata to lrmi specification
+ effectiveness: `60-80` (optional, string) - returns resources within an effectiveness range. If one value is set it will be assumed to be the minimum and 100% will be set as the maximum.
+ embeddable: `true` (optional, boolean) - returns only resources with embeddable links(relevant mostly to videos).
+ case_identifiers: `358a58d9-3138-5fcc-ae91-6e54d277c91f` (optional, array[string]) - returns resources aligned to specfic case identifier.
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"meta":
{
"pagination":
{
"offset":0,
"total_entries":258213,
"entries":1,
"limit":1
},
"flags":
{
"have_gallery":false
}
},
"resources": [
{
"standard_ids": [1, 2],
"standard_idents": [
"K.G.2",
"K.G.3"
],
"area_ids": [1,3],
"subject_ids": [2,4],
"grades_range": "K-5",
"is_premium": false,
"publisher": "Mr. Smith",
"description": "Mr. Smith sings a cute song to teach kids 3D shapes. He helps build real world connections while students learn the cube, rectangular prism, cylinder, sphere, and pyramid. This is a good resource to help introduce and/or review this important skill.",
"effectiveness": 88,
"resource_type": "video",
"id": 178375,
"thumbnails": {
"mini": "https://mini_thumb/default.jpg",
"small": "https://small_thumb/default.jpg",
"medium": "https://medium_thumb/default.jpg",
"large": "https://large_thumb/default.jpg"
},
"title": "Teacher Tipster-3D Shapes Song-Teaching 3 Dimensional Shapes",
"share_url": "https://www.opened.com/resources/178375?partner_id1&simplifiedView=true",
"student_url": "https://www.opened.com/resources/383255?partner_id=id&simplifiedView=true&student_view=true",
"rating": 4,
"duration": 130,
"use_rights_url":"https://creativecommons.org/licenses"
}
]
}
+ Request (application/json; charset=utf-8)
{"schema_org": true}
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"resources": [
{
"resource_id": 178375,
"name": "Learing about Parcc",
"effectiveness": "88",
"educationalAlignment": [
{
"targetName": "PARCC.ELA.RV3.1",
"alignmentType": "teachers",
"educationalFramework": "PARCC Common Core ELA/Literacy Summative Assessments",
"targetDescription": "Use units as a way to understand problems",
"targetUrl": "https://common_core_ela_material.com"
}
],
"publisher": "Mr. Smith",
"author": "Mr. Smith",
"description": "Mr. Smith sings a cute song to teach kids 3D shapes. He helps build real world connections while students learn the cube, rectangular prism, cylinder, sphere, and pyramid. This is a good resource to help introduce and/or review this important skill.",
"thumbnailUrl": "https://opened.s3.amazonaws.com/pictures/178375/thumb/default.jpg?1359909018",
"url": "https://www.opened.com/resources/178375?partner_id1&simplifiedView=true",
"dateCreated": null,
"inLanguage": "English",
"useRightsUrl": "free",
"timeRequired": 130.0,
"typicalAgeRange": "K-2",
"interactivityType": "expositive",
"about": "Unknown/Unknown",
"intendedEndUserRole": "student",
"educationalUse": "Video",
"learningResourceType": "Video"
}
],
"meta":
{
"pagination":
{
"offset":0,
"total_entries":258213,
"entries":1,
"limit":1
},
"flags":
{
"have_gallery":false
}
}
}
## Get Resource [/1/resources/{resource_id}]
### GET
Show specified resource.
+ Parameters
+ resource_id: `185352` (required, number) - The unique identifier of the resource
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"resource":{
"id":23145,
"standard_ids": [1, 2],
"standard_idents":["K.CC.1","K.CC.4"],
"grades_range":"K",
"contribution_name":"WatchKnowLearnCommonCore",
"publisher":"SamplePublisher",
"description":"In this classic Sesame Street cartoon, the Bellhop has to find the parents of two lost kids. \u00a0Betty and Bobby Blobby are lost in the lobby.",
"duration":120,
"resource_type":"video",
"thumbnails": {
"mini":"https://opened.s3.amazonaws.com/pictures/110710/thumb/110710.jpg?1377325449",
"small":"https://opened.s3.amazonaws.com/pictures/110710/thumb/110710.jpg?1377325449",
"medium":"https://opened.s3.amazonaws.com/pictures/110710/thumb/110710.jpg?1377325449",
"large":"https://opened.s3.amazonaws.com/pictures/110710/thumb/110710.jpg?1377325449"
},
"title":"The Bellhop Counts to 2",
"share_url":"https://www.opened.com/resources/178375?partner_id1&simplifiedView=true",
"student_url":"https://www.opened.com/resources/383255?partner_id=id&simplifiedView=true&student_view=true",
"rating":3,
"area_ids":[2],
"subject_ids":[18],
"effectiveness":88,
"use_rights_url":"https://creativecommons.org/licenses"
}
}
## Create Resource [/1/resources]
### Create [POST]
Create a resource in the OpenEd catalog.
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer TOKEN
+ Attributes
+ url (required,string) - where is the resource hosted
+ title (required,string) - what do you want to call the resource. It doesn't have to match what you have on your site
+ description (required, string) - more information about the resource. You are strongly urged to supply a description as it helps the OpenEd recommendation engine highlight your resources
+ standard_idents (optional,string) - comma-separated list of standard identifiers aligned to the resource. You do not have to supply this. OpenEd will attempt to determine alignments once your resource is contributed
+ subject (optional, string) - the list of subjects (from the OpenEd area/subject taxonomy described below) associated with the resource
+ grades_range (optional,string) - in the form "lowgrade-highgrade", e.g. "K-4" where "K" must be capitalized
+ publisher (optional,string) - your site as the publisher so we can give you credit. Defaults to OAuth username.
+ resource_type (required,string) - Either "video", "game", "assessment", "homework" or "other". Default to "other" if it is not identified as a video
+ rating (optional,string) - The rating of the resource on a scale of "1" to "5" if you have one on your site
+ image (optional,string) - An image that acts as a preview of the resource. This is a URL link.
+ contribution_name (optional, string) - the place where the resource was contributed from. Not neccessarily the publisher.
+ Body
{
"url": "http://youtube.com/3455",
"title": "New Resource",
"description": "my new learning video",
"standard_idents": "K.CC.1",
"subject": "Math",
"grades_range": "K-2",
"publisher": "PBS",
"resource_type": 'video',
"image": "http://path_to_hosted_image.com",
"contribution_name": "OpenedEd"
}
+ Response 200 (application/json; charset=utf-8)
{
"notice": "Resource was added successfully",
"id": 1
}
## Update Resource [/1/resources/{id}]
### Update [PUT]
Update an existing resource in the OpenEd catalog.
+ Parameters
+ id: `34521` (required, number) - the existing resource id
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer TOKEN
+ Attributes
+ url (required,string) - where is the resource hosted
+ title (required,string) - what do you want to call the resource. It doesn't have to match what you have on your site
+ description (required, string) - more information about the resource. You are strongly urged to supply a description as it helps the OpenEd recommendation engine highlight your resources
+ standard_idents (optional,string) - comma-separated list of standard identifiers aligned to the resource. You do not have to supply this. OpenEd will attempt to determine alignments once your resource is contributed
+ subject (optional, string) - the list of subjects (from the OpenEd area/subject taxonomy describe below) associated with the resource
+ grades_range (optional,string) - in the form "lowgrade-highgrade", e.g. "K-4" where "K" must be capitalized
+ publisher (optional,string) - your site as the publisher so we can give you credit. Defaults to OAuth username.
+ resource_type (required, string) - Either "video", "game", "assessment", "homework" or "other". Default to "other" if it is not identified as a video
+ rating (optional,string) - The rating of the resource on a scale of "1" to "5" if you have one on your site
+ image (optional,string) - An image that acts as a preview of the video. When possible with other resource types thumbnails are encouraged. This is a URL link.
+ contribution_name (optional, string) - the place where the resource was contributed from. Not neccessarily the publisher.
+ Body
{
"url": "http://youtube.com/3455",
"title": "New Resource",
"description": "my new learning video",
"standard_idents": "K.CC.1",
"subject": "Math",
"grades_range": "K-2",
"publisher": "PBS",
"resource_type": 'video',
"image": "http://path_to_hosted_image.com",
"contribution_name": "OpenedEd"
}
+ Response 200 (application/json; charset=utf-8)
{
"notice": "Resource was updated successfully"
}
# Group Standards
OpenEd also allows you to search for information on the standards themselves (in addition to finding resources for standards).
Standards are organized into "standard groups" such as "Common Core Math" and "Common Core Language Arts".
Within a standard group there are "grade groups" such as "Elementary" and "Middle School".
Each grade group has a set of "categories" (sometimes known as "strands"), such as "Geometry".
Within categories there are individual standards. This method of organizing standards was created by the Common Core State Standards,
but we use it to structure all standard groups.
## Standard Groups [/1/standard_groups.json]
### GET
To navigate the standards hierarchies you first need to get the list of standard groups.
+ Request
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"standard_groups": [
{
"id": 4,
"title": "Common Core Math",
"grades_range": "K-12",
"area_id": 1
},
{
"id": 2,
"title": "Common Core Language Arts",
"grades_range": "K-12",
"area_id": 2
}
],
"meta": {
"pagination": {
"offset": 0,
"total_entries": 2,
"entries": 2,
"limit": 50
}
}
}
## Get Standard Group [/1/standard_groups/{id}.json]
### GET
Show specified standard group.
+ Parameters
+ id (number, `4`) - A unique identifier of the standard group
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"standard_group": {
"id": 4,
"title": "Common Core Math",
"grades_range": "K-12",
"area_id": 1
}
}
## Grade Groups [/1/grade_groups.json{?standard_group}]
### GET
Get the list of grade groups, typically for a particular standard group.
+ Parameters
+ standard_group: `2` (optional, number) - The id of the standard group you want grade groups for.
+ Request
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"grade_groups": [
{
"id": 46,
"title": "Elementary",
"grades_range": "K-5",
"standard_group_ids": [2,4]
},
{
"id": 47,
"title": "Middle School",
"grades_range": "6-8",
"standard_group_ids": [2,4]
},
{
"id": 48,
"title": "High School",
"grades_range": "9-12",
"standard_group_ids": [2]
}
],
"meta": {
"pagination": {
"offset": 0,
"total_entries": 3,
"entries": 3,
"limit": 50
}
}
}
## Get Grade Group [/1/grade_groups/{id}.json]
### GET
Show specified grade group.
+ Parameters
+ id (number, `46`) - A unique identifier of the grade group
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"grade_group": {
"id": 46,
"title": "Elementary",
"grades_range": "K-5",
"standard_group_ids": [2,4]
}
}
## Categories [/1/categories.json{?standard_group,grade_group}]
### GET
You can get a list of categories based on several criteria.
+ Parameters
+ standard_group: `2` (required, number) - shows all categories within a standard group.
+ grade_group: `46` (optional, number) - restricts the categories to those associated with a specific grade group.
+ Request
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"categories": [
{
"id": 115,
"title": "Geometry (Elementary)",
"standard_group_id": 4,
"grade_group_id": 46,
"grades_range": "K-5"
},
{
"id": 121,
"title": "Functions",
"standard_group_id": 4,
"grade_group_id": 47,
"grades_range": "8"
},
{
"id": 125,
"title": "The Number System",
"standard_group_id": 4,
"grade_group_id": 47,
"grades_range": "6-8"
}
],
"meta": {
"pagination": {
"offset": 0,
"total_entries": 3,
"entries": 3,
"limit": 50
}
}
}
## Get Category [/1/categories/{id}.json]
### GET
Show specified category.
+ Parameters
+ id (number, `115`) - A unique identifier of the category
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"category": {
"id": 115,
"title": "Geometry (Elementary)",
"standard_group_id": 4,
"grade_group_id": 46,
"grades_range": "K-5"
}
}
## Standards [/1/standards.json{?category,grades_range,key_words}]
### GET
Get the list of standards based on the category.
+ Parameters
+ category: `256` (required, number) - standards for a given standard category.
+ grades_range: `K-5` (optional, string) - just the standards relevant to a given grades range, generally combined with standard group or grade group.
+ key_words: `counting` (optional, array[string]) - an array of strings to search standard list by.
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"standards": [
{
"id": 21461,
"identifier": "K.CC.1",
"title": "Count to 100 by ones and by tens.",
"category_id": 115,
"grades_range": "2"
},
{
"id": 20916,
"identifier": "K.CC.2",
"title": "Count forward beginning from a given number within the known sequence (instead of having to begin at 1).",
"category_id": 115,
"grades_range": "2"
},
{
"id": 20917,
"identifier": "K.CC.3",
"title": "Write numbers from 0 to 20. Represent a number of objects with a written numeral 0-20 (with 0 representing a count of no objects).",
"category_id": 115,
"grades_range": "2"
}
],
"meta": {
"pagination": {
"offset": 0,
"total_entries": 3,
"entries": 3,
"limit": 50
}
}
}
## Get Standard [/1/standards/{id}.json]
### GET
Show specified standard.
+ Parameters
+ id (number, `21461`) - A unique identifier of the standards
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"standard": {
"id": 21461,
"identifier": "K.CC.1",
"title": "Count to 100 by ones and by tens.",
"category_id": 115,
"grades_range": "2"
}
}
# Group Area / Subject Taxonomy
OpenEd categorizes all resources in an area/subject taxonomy. The top level is areas, such as Math and Language Arts. The next level is subject, such as Geometry or Writing.
## Areas [/1/areas.json]
### GET
Get a list of areas.
+ Request
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"areas": [
{
"id": 1,
"title": "Mathematics",
"grades_range": "K-12"
},
{
"id": 2,
"title": "Language Arts",
"grades_range": "K-12"
}
],
"meta": {
"pagination": {
"offset": 0,
"total_entries": 2,
"entries": 2,
"limit": 50
}
}
}
## Get Area [/1/areas/{id}.json]
### GET
Show specified area.
+ Parameters
+ id (number, `1`) - A unique identifier of the area
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"area": {
"id": 1,
"title": "Mathematics",
"grades_range": "K-12"
}
}
## Subjects [/1/subjects.json{?area}]
### GET
Get the list of subjects based on supplied area.
+ Parameters
+ area: `1` (required,number) - the area you want subjects for.
+ Request
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"subjects": [
{
"id": 7,
"title": "Functions",
"area_id": 1,
"grades_range": ""
},
{
"id": 4,
"title": "Trigonometry",
"area_id": 1,
"grades_range": ""
},
{
"id": 8,
"title": "Expressions, Equations and Inequalities",
"area_id": 1,
"grades_range": ""
}
],
"meta": {
"pagination": {
"offset": 0,
"total_entries": 3,
"entries": 3,
"limit": 50
}
}
}
## Get Subject [/1/subjects/{id}.json]
### GET
Show specified subject.
+ Parameters
+ id (number, `7`) - A unique identifier of the subject
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"subject": {
"id": 7,
"title": "Functions",
"area_id": 1,
"grades_range": ""
}
}
# Group Publisher
## Publishers [/1/publishers.json]
### GET
Retrieve list of publishers.
+ Request
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"meta": {
"pagination": {"offset":0,"total_entries":null,"entries":null,"limit":50}
},
"publishers": [
{
"id":32539,
"title":"Smithsonian Institution"
},
{
"id":32539,
"title":"Sample Publisher"
}
]
}
## Get Publisher [/1/publishers/{id}.json]
### GET
Show specified publisher
+ Parameters
+ id (number, `1`) - A unique identifier of the publisher
+ Request (application/json)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"publisher": {
"id":32539,
"title":"Smithsonian Institution"
}
}
# Group Manage teacher's classes and students
Partner's API endpoint is https://partner.opened.com/
## Teacher's Classes [/1/teachers/classes]
Available for teachers only
### Create a New Class [POST /1/teachers/classes]
You may create your own class using this action.
+ Request (application/json; charset=utf-8)
+ Attributes
+ class (object, required) - title (string), grades_range (string)
+ title: `First Grade Class` (string, required) - The class title, required
+ grades_range: `K-2` (string, optional) - dash separated grade range K-12
+ teacher_id: `123` (number, optional) - the id of the teacher to create class for
+ Headers
Authorization: Bearer [TOKEN]
+ Body
{
"class": {
"title": "New Class",
"grades_range": "K-2"
}
}
+ Response 201 (application/json; charset=utf-8)
+ Body
{
"class": {
"id": 4812,
"title": "My class",
"created_at": "2015-09-18T22:30:03.142Z",
"student_ids": [],
"standard_area_ids": [],
"grades_range": "5",
"owner_id": 16370
},
"owners": [
{
"id": 16370,
"first_name": "Leonid",
"last_name": "Morozov",
"username": "leonid.morozov"
}
],
"standard_areas": [],
"students": []
}
### List classes [GET /1/teachers/classes{?ids}]
You can get a list of your classes by passing an array of class ids.
+ Parameters
+ ids (optional, array[int]) - array of class `ids`
+ Request
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"classes": [
{
"id": 4812,
"title": "Grade 5",
"created_at": "2015-09-18T22:30:03.142Z",
"student_ids": [],
"standard_area_ids": [],
"grades_range": "5",
"owner_id": 16370
}
],
"owners": [
{
"id": 16370,
"first_name": "Leonid",
"last_name": "Morozov",
"username": "leonid.morozov"
}
],
"standard_areas": [],
"students": []
}
### Get Class [GET /1/teachers/classes/{class_id}]
You can get a user's class.
+ Parameters
+ class_id (required, number, `123`) - Class `id`
+ Request
+ Headers
Authorization: Bearer [TOKEN]
+ Response 200 (application/json; charset=utf-8)
{
"class": {
"id": 4812,
"title": "Grade 5",
"created_at": "2015-09-18T22:30:03.142Z",
"student_ids": [],
"standard_area_ids": [],
"grades_range": "5",
"owner_id": 16370
},
"owners": [
{
"id": 16370,
"first_name": "Leonid",
"last_name": "Morozov",
"username": "leonid.morozov"
}
],
"standard_areas": [],
"students": []
}
### Update Class [PUT /1/teachers/classes/{class_id}]
You may update your own class using this action.
+ Parameters
+ class_id (required, number, `123`) - Class `id`
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer [TOKEN]
+ Attributes
+ title: `New Class Title` (string, optional) - The class title
+ grades_range: `K-3` (string, optional) - class grades_range, in formats: '5', '5-5', '6-8'
+ Body
{
"class": {
"title": "My class new title",
"grades_range": "6-8"
}
}
+ Response 200 (application/json; charset=utf-8)
+ Body
{
"class": {
"id": 4812,
"title": "My class new title",
"created_at": "2015-09-18T22:30:03.142Z",
"student_ids": [],
"standard_area_ids": [],
"grades_range": "6-8",
"owner_id": 16370
},
"owners": [
{
"id": 16370,
"first_name": "Leonid",
"last_name": "Morozov",
"username": "leonid.morozov"
}
],
"standard_areas": [],
"students": []
}
### Remove a Class [DELETE /1/teachers/classes/{class_id}]
You may delete your own class using this action.
+ Parameters
+ class_id (required, number, `123`) - Class `id`
+ Request
+ Headers
Authorization: Bearer [TOKEN]
+ Response 204
### Create a Student [POST /1/teachers/students]
You may create your own student and add it to your class.
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer [TOKEN]
+ Attributes
+ student (object)
+ email: `student@email.com` (string, required) - students email, username or email is required
+ first_name: `test first name` (optional, string) - student's first_name
+ last_name:`test last name` (optional, string) - Student's last_name
+ username: `test username` (optional, string) - student's username, username or email is required
+ password: `password` (optional, string) - student's password
+ class_ids: `[123]` (optional, array[number]) - ids of classes new student needs to be added
+ Body
{
"student":{
"email": "student@email.com",
"first_name":"Student",
"last_name":"2",
"username":"student2",
"password":"password",
"class_ids":[4812]
}
}
+ Response 201 (application/json; charset=utf-8)
+ Body
{
"student":{
"id":16372,
"first_name":"Student",
"last_name":"2",
"username":"student2",
"password":"password",
"class_ids":[4812]
}
}
### Add existing students to the Class [POST /1/teachers/classes/{class_id}/add_students]
This allows you to manage existing students in the classes.
You can create students and then add them to an existing class.
+ Parameters
+ class_id (required, number, `123`) - Class `id`
+ Request (application/json; charset=utf-8)
+ Attributes
+ student_ids: [`16372`] (required, array) - array of student ids
+ Headers
Authorization: Bearer [TOKEN]
+ Body
{
"student_ids": [16372]
}
+ Response 200 (application/json; charset=utf-8)
+ Body
{
"class": {
"id": 4812,
"title": "My class new title",
"created_at": "2015-09-18T22:30:03.142Z",
"student_ids": [],
"standard_area_ids": [],
"grades_range": "6-8",
"owner_id": 16370
},
"owners": [
{
"id": 16370,
"first_name": "Leonid",
"last_name": "Morozov",
"username": "leonid.morozov"
}
],
"standard_areas": [],
"students": [
{
"id":16371,
"first_name":"Student",
"last_name":"1",
"username":"student1",
"password":"password"
},
{
"id":16372,
"first_name":"New Student",
"last_name":"1",
"username":"student2",
"password":"password2"
}
]
}
### Remove students from the Class [POST /1/teachers/classes/{class_id}/remove_students]
+ Parameters
+ class_id (required, number, `123`) - Class `id`
+ Request (application/json; charset=utf-8)
+ Attributes
+ student_ids: [`16372`] (required, array) - array of student ids
+ Headers
Authorization: Bearer [TOKEN]
+ Body
{
"student_ids": [16372]
}
+ Response 200 (application/json; charset=utf-8)
+ Body
{
"class": {
"id": 4812,
"title": "My class new title",
"created_at": "2015-09-18T22:30:03.142Z",
"student_ids": [],
"standard_area_ids": [],
"grades_range": "6-8",
"owner_id": 16370
},
"owners": [
{
"id": 16370,
"first_name": "Leonid",
"last_name": "Morozov",
"username": "leonid.morozov"
}
],
"standard_areas": [],
"students": [
{
"id":16371,
"first_name":"Student",
"last_name":"1",
"username":"student1",
"password":"password"
}
]
}
## Teacher's Students [/1/teachers/students]
Available for teachers only.
### List students [GET /1/teachers/students{?ids}]
Get a list of your students passing an array of student ids.
+ Parameters
+ ids (optional, array[int]) - list of student `id`
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer [TOKEN]
+ Response 200 (application/json; charset=utf-8)
{
"students":[
{
"id":16371,
"first_name":"Student",
"last_name":"1",
"username":"student1",
"password":"password",
"class_ids":[4812]
},
{
"id":16372,
"first_name":"New Student",
"last_name":"1",
"username":"student2",
"password":"password2",
"class_ids":[4812]
}
]
}
### Get Student [GET /1/teachers/students/{student_id}]
You can get an individual student object.
+ Parameters
+ student_id (required, number, `123`) - Student `id`
+ Request
+ Headers
Authorization: Bearer [TOKEN]
+ Response 200 (application/json; charset=utf-8)
{
"student":{
"id":16372,
"first_name":"New Student",
"last_name":"1",
"username":"student2",
"password":"password2",
"class_ids":[4812]
}
}
### Update Student [PUT /1/teachers/students/{student_id}]
You can update a student object.
+ Parameters
+ student_id (required, number, `123`) - Class `id`
+ Request (application/json; charset=utf-8)
+ Attributes
+ first_name: `test first name` (optional, string) - student first name
+ last_name: `test last name` (optional, string) - student last name
+ password: `password` (optional, string) - student password
+ Headers
Authorization: Bearer [TOKEN]
+ Body
{
"student":{
"first_name":"New Student",
"last_name":"1",
"password":"password2"
}
}
+ Response 200 (application/json; charset=utf-8)
+ Body
{
"student":{
"id":16372,
"first_name":"New Student",
"last_name":"1",
"username":"student2",
"password":"password2",
"class_ids":[4812]
}
}
### Remove a Student [DELETE /1/teachers/students/{student_id}]
You may delete your own student using this action.
+ Parameters
+ student_id (required, number, `123`) - Class `id`
+ Request (application/json)
+ Headers
Authorization: Bearer [TOKEN]
+ Response 204
# Group Assessment Results
## Get Assessment Results [/1/assessment_runs.json/{?resource_id}]
### GET
You can get a list of the last five assessment runs for your currently logged in user.
+ Parameters
+ resource_id (number, required, `1069949`) - The resource id of a resource with
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Bearer TOKEN
+ Response 200 (application/json; charset=utf-8)
{
"assessment_runs": [
{
"id": 7,
"created_at": "2016-03-04T18:56:17.945Z",
"finished_at": "2016-03-04T18:56:17.945Z",
"score": 70.0,
"assessment_id": 1069949,
"user_id": 16759,
"mastery_level": 90,
"assessment_near_mastery_percent": 70,
"assessment_mastery_percent": 90,
"assessment_title": "HSS.CED.2: Create equations in two or more variables",
"score_description": ""
}
]
}
# Group School
## Create a School [/1/schools]
### Create [POST]
You can create schools to be used later with your user accounts. These schools must be created with an NCES ID and school name.
+ Request (application/json)
+ Attributes
+ nces_id: school's NCES ID (required)
+ name: school's name (required)
+ address: school's address (string, optional)
+ city: school's city (string, optional)
+ state: school's state (string, optional)
+ zip: school's zip code (string, optional)
+ phone: school's phone number (string, optional)
+ low_grade: school's lowest grade (string, optional)
+ high_grade: school's highest grade (string, optional)
+ Headers
Authorization: Bearer [TOKEN]
+ Body
{
"nces_id":"1",
"name":"Union Middle School",
"address":"123 Union Av",
"city": "San Jose",
"state": "Ca",
"zip": "95124",
"low_grade": "6",
"high_grade": "8"
}
}
+ Response 200
{
"school":{
"id":65945,
"name":"Example Middle",
"nces_id":"111111",
"low_grade":"6",
"high_grade":"8",
"phone":"1-555-400-5555",
"address":"100 First st.",
"city":"San Jose",
"state":"CA",
"zip":"99999"
}
}
+ Response 422
{
"error": "error message"
}
# Group Examples
###[Roster Upload](https://github.com/openedinc/oneroster/blob/master/opened/1r-oe.rb)
###[Resource Search](https://github.com/openedinc/opened-api-consumer)
###[Manage Classes and Students](https://github.com/openedinc/class-roster-sample)
# Group API Commons
## Manifest
Here is the API Commons Manifest for the OpenEd API.
{
"apis": [
{
"name": "OpenEd API",
"description": "Search for resources for standards or by topic. Get information on standards. Get information on our area/subject taxonomy of resources.",
"image": "https://pbs.twimg.com/profile_images/378800000580251314/04fe1856596c096c1b5da337946aba45_bigger.png",
"keywords": "ed tech, resources, videos, games, K-12, flipped classroom, Common Core",
"license": "http://opensource.org/licenses/MIT",
"attribution": "OpenEd, Inc.",
"url": "http://docs.opened.apiary.io",
"definitions": [
{
"type": "[API Blueprint]",
"url": "https://github.com/apiaryio/api-blueprint"
}
]
}
],
"tags": "api-commons-manifest",
"updated": "11/30/2013"
}