ylqjgm
/
canvas-lms
mirror of https://github.com/instructure/canvas-lms.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
canvas-lms/doc/api
History
Jesse Poulos ec4ed44c61 Document oauth_compliant as a possible XML config option 
Currently, there is no documentation that shows how to configure an
external tool so that Canvas omits launch URL query parameters from the
POST body (see PLAT-2025). This update adds that documentation.

Test plan:
1) run localhost Canvas
2) build the API docs (docker-compose run --rm web bundle exec rake
doc:api)
3) navigate to the following:
<your host url>/doc/api/file.tools_xml.html
4) check for spelling, grammar, accuracy of information and that the new
link works

Fixes PLAT-2146

Change-Id: Ie111872b39ae212d473034d74464bc1a011bf7ea
Reviewed-on: https://gerrit.instructure.com/99714
Tested-by: Jenkins
Reviewed-by: Andrew Butterfield <abutterfield@instructure.com>
QA-Review: August Thornton <august@instructure.com>
Product-Review: Jesse Poulos <jpoulos@instructure.com>
 		2017-01-16 22:51:18 +00:00
..
appendix/html integrate yard-appendix plugin with canvas YARD cfg 2013-02-08 11:50:37 -07:00
docstring/html rename doc/templates/rest to doc/api 2011-12-30 09:00:27 -07:00
fulldoc/html Fix overlapping text in API documentation tables 2016-11-22 02:56:36 +00:00
layout/html Add content item to API docs and add deprecation resource select 2016-10-28 19:53:36 +00:00
method_details/html fix api route display 2016-01-20 16:48:32 +00:00
tags api doc styling updates 2016-01-20 21:09:57 +00:00
topic/html federated attributes backend 2016-07-13 19:00:00 +00:00
README.md document encouraging using string ids 2016-11-22 02:11:13 +00:00
assignment_tools.md Document ltiLaunchUrl as a possible resultData node 2017-01-13 20:23:07 +00:00
compound_documents.md improve api documentation syntax highlighting 2016-01-15 23:25:27 +00:00
content_item.md Add content item to API docs and add deprecation resource select 2016-10-28 19:53:36 +00:00
editor_button_tools.md Clarify "rich editor" and "link selection" api docs 2016-11-09 20:59:58 +00:00
endpoint_attributes.md improve api documentation syntax highlighting 2016-01-15 23:25:27 +00:00
file_uploads.md improve api documentation syntax highlighting 2016-01-15 23:25:27 +00:00
homework_submission_tools.md fixes improperly formatted external tool documentation 2013-10-31 20:43:09 +00:00
link_selection_tools.md Clarify "rich editor" and "link selection" api docs 2016-11-09 20:59:58 +00:00
live_events.md ensure cyoe only references fully graded, non-muted assignments 2017-01-11 20:21:40 +00:00
masquerading.md improve api documentation syntax highlighting 2016-01-15 23:25:27 +00:00
navigation_tools.md extension tool launches default to settings from main tool 2012-06-26 12:10:36 -06:00
oauth.md Update OAuth2 documentation in API docs 2017-01-04 22:23:48 +00:00
oauth_endpoints.md Update OAuth2 documentation in API docs 2017-01-04 22:23:48 +00:00
object_ids.md document and extend usage of integration_id for users 2016-02-18 20:11:01 +00:00
pagination.md change api pagination to include the current page link 2013-08-16 19:13:25 +00:00
sis_csv.md remove invalid line from api doc 2016-12-21 22:10:18 +00:00
throttling.md add headers to inform the client where they stand for throttling 2015-04-09 15:52:22 +00:00
tools_intro.md Add content item to API docs and add deprecation resource select 2016-10-28 19:53:36 +00:00
tools_variable_substitutions.head.md Better LTI Variable Substitution Docs 2016-05-02 19:15:46 +00:00
tools_variable_substitutions.md add custom variable for institution assigned (i.e. sis) email 2017-01-16 21:02:51 +00:00
tools_xml.md Document oauth_compliant as a possible XML config option 2017-01-16 22:51:18 +00:00
xapi.md improve api documentation syntax highlighting 2016-01-15 23:25:27 +00:00

README.md

Welcome to the Canvas LMS API Documentation

Canvas LMS includes a REST API for accessing and modifying data externally from the main application, in your own programs and scripts. This documentation describes the resources that make up the API.

To get started, you'll want to review the general basics, including the information below and the page on Authentication using OAuth2.

Schema

All API access is over HTTPS, against your normal Canvas domain.

All API responses are in JSON format.

All integer ids in Canvas are 64 bit integers. String ids are also used in Canvas.

To force all ids to strings add the request header Accept: application/json+canvas-string-ids This will cause Canvas to return even integer IDs as strings, preventing problems with languages (particularly JavaScript) that can't properly process large integers.

All boolean parameters can be passed as true/false, t/f, yes/no, y/n, on/off, or 1/0. When using JSON format, a literal true/false is preferred, rather than as a string.

For POST and PUT requests, parameters are sent using standard HTML form encoding (the application/x-www-form-urlencoded content type).

POST and PUT requests may also optionally be sent in JSON format format. The content-type of the request must be set to application/json in this case. There is currently no way to upload a file as part of a JSON POST, the multipart form type must be used.

As an example, this HTML form request:

name=test+name&file_ids[]=1&file_ids[]=2&sub[name]=foo&sub[message]=bar&flag=y

would translate into this JSON request:

{ "name": "test name", "file_ids": [1,2], "sub": { "name": "foo", "message": "bar" }, "flag": true }

With either encoding, all timestamps are sent and returned in ISO 8601 format (UTC time zone):

YYYY-MM-DDTHH:MM:SSZ

Authentication

API authentication is done with OAuth2. If possible, using the HTTP Authorization header is recommended. Sending the access token in the query string or POST parameters is also supported.

OAuth2 Token sent in header:

curl -H "Authorization: Bearer <ACCESS-TOKEN>" "https://canvas.instructure.com/api/v1/courses"

OAuth2 Token sent in query string:

curl "https://canvas.instructure.com/api/v1/courses?access_token=<ACCESS-TOKEN>"

Read more about OAuth2 and how to get access tokens.

API Terms of Service

Please carefully review The Canvas Cloud API Terms of Service before using the API.

SSL

Note that if you make an API call using HTTP instead of HTTPS, you will be redirected to HTTPS. However, at that point, the credentials have already been sent in clear over the internet. Please make sure that you are using HTTPS.

About this Documentation

This documentation is generated directly from the Canvas LMS code itself. You can generate this documentation yourself if you've set up a local Canvas environment following the instructions on Github, run the following command from your Canvas directory:

bundle exec rake doc:api