Andal.LND/edx-platform
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reorganize and update API documentation

Browse Source
This commit is contained in:
Sylvia Pearce
2015-06-24 17:17:16 -04:00
parent 3cdad4677f
commit d2b6ac84d3
29 changed files with 744 additions and 773 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/en_us/platform_api/source/conf.py
View File

@@ -183,7 +183,13 @@ MOCK_MODULES = [
'update_account_settings',
'serializers',
'profile_images.images',
'xmodule.course_module'
'xmodule.course_module',
'user_api.accounts.api',
'user_api.accounts.serializers',
'ecommerce_api_client',
'client',
'ecommerce_api_client.client',
'ecommerce_api_client.exceptions'
]

27
docs/en_us/platform_api/source/course_structure/endpoints.rst
View File

@@ -1,27 +0,0 @@
.. _EdX Platform Course Structure API Endpoints:
################################################
Course Structure API Endpoints
################################################
You use the Course Structure API to view information about
courses.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Get a list of courses in the edX platform <Get a List of Courses>`
- GET /api/course_structure/v0/courses/
* - :ref:`Get details about a course <Get Course Details>`
- GET /api/course_structure/v0/courses/{course_id}/
* - :ref:`Get a course's structure, or blocks <Get the Course Structure>`
- GET /api/course_structure/v0/course_structures/{course_id}/
* - :ref:`Get a course's grading policy <Get the Course Grading Policy>`
- GET /api/course_structure/v0/grading_policies/{course_id}/

1
docs/en_us/platform_api/source/course_structure/index.rst
View File

@@ -8,5 +8,4 @@ Course Structure API Version 0
:maxdepth: 2
overview
endpoints
course_structure

28
docs/en_us/platform_api/source/course_structure/overview.rst
View File

@@ -16,16 +16,24 @@ significant enhancements to this API. Currently the Course Structure API is for
internal use only; third parties cannot use the API to access course structure
data.
***********************************************
Course Structure API Capabilities
***********************************************
**********************************************
Course Structure API Resources and Endpoints
**********************************************
With the Course Structure API, you can complete these tasks.
The Course Structure API supports the following resources, tasks, methods, and
endpoints.
* :ref:`Get a list of courses in the edX platform <Get a List of Courses>`
.. list-table::
:widths: 10 70
:header-rows: 1
* :ref:`Get details about a course <Get Course Details>`
* :ref:`Get a course's structure, or blocks <Get the Course Structure>`
* :ref:`Get a course's grading policy <Get the Course Grading Policy>`
* - To:
- Use this endpoint:
* - :ref:`Get a list of courses in the edX platform <Get a List of Courses>`
- GET /api/course_structure/v0/courses/
* - :ref:`Get details about a course <Get Course Details>`
- GET /api/course_structure/v0/courses/{course_id}/
* - :ref:`Get a course's structure, or blocks <Get the Course Structure>`
- GET /api/course_structure/v0/course_structures/{course_id}/
* - :ref:`Get a course's grading policy <Get the Course Grading Policy>`
- GET /api/course_structure/v0/grading_policies/{course_id}/

26
docs/en_us/platform_api/source/enrollment/endpoints.rst
View File

@@ -1,26 +0,0 @@
.. _edX Enrollment API Endpoints:
################################################
Enrollment API Endpoints
################################################
You use the Enrollment API to view information about users and
their course enrollments, course information, and videos and transcripts.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Get the user's enrollment status in a course <Get the Users Enrollment Status in a Course>`
- /api/enrollment/v1/enrollment/{user_id},{course_id}
* - :ref:`Get enrollment details for a course<Get Enrollment Details for a Course>`
- /api/enrollment/v1/course/{course_id}
* - :ref:`View a user's enrollments <View and add to a Users Course Enrollments>`
- /api/enrollment/v1/enrollment
* - :ref:`Enroll a user in a course <View and add to a Users Course Enrollments>`
- /api/enrollment/v1/enrollment{“course_details”:{“course_id”:“*course_id*”}}

121
docs/en_us/platform_api/source/enrollment/enrollment.rst
View File

@@ -1,14 +1,17 @@
##################################################
Enrollment API
Enrollment API
##################################################
This page contains information on using the Enrollment API to complete
the following actions.
You can use the Enrollment API to complete the following tasks.
* :ref:`Get the user's enrollment status in a course <Get the Users Enrollment Status in a Course>`
* :ref:`Get enrollment details for a course<Get Enrollment Details for a Course>`
* :ref:`View a user's enrollments <View and add to a Users Course Enrollments>`
* :ref:`Enroll a user in a course <View and add to a Users Course Enrollments>`
* :ref:`Get the user's enrollment status in a course <Get the Users Enrollment
Status in a Course>`.
* :ref:`Get enrollment details for a course<Get Enrollment Details for a
Course>`.
* :ref:`View a user's enrollments <View and add to a Users Course
Enrollments>`.
* :ref:`Enroll a user in a course <View and add to a Users Course
Enrollments>`.
.. _Get the Users Enrollment Status in a Course:
@@ -33,37 +36,34 @@ Get the User's Enrollment Status in a Course
"mode": "honor",
"is_active": true,
"course_details": {
"course_end": "2015-06-30T05:00:00Z",
"course_start": "2015-02-05T05:00:00Z",
"course_modes": [
{
"slug": "honor",
"name": "Honor Code Certificate",
"min_price": 0,
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null,
"sku": null
}
],
"enrollment_start": "2015-01-01T05:00:00Z",
"enrollment_end": "2015-02-13T05:00:00Z",
"invite_only": false,
"course_id": "edX/DemoX/Demo_Course"
},
"user": "staff"
"course_id": "edX/DemoX/Demo_Course",
"enrollment_end": null,
"course_modes": [
{
"slug": "honor",
"name": "Honor Code Certificate",
"min_price": 0,
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null
}
],
"enrollment_start": null,
"invite_only": false
},
"user": "staff"
}
.. _Get Enrollment Details for a Course:
************************************
Get Enrollment Details for a Course
************************************
**************************************************
Get the User's Enrollment Information for a Course
**************************************************
.. autoclass:: enrollment.views.EnrollmentCourseDetailView
**Example response showing a user's course enrollments**
**Example response showing a user's course enrollment information**
.. code-block:: json
@@ -73,8 +73,8 @@ Get Enrollment Details for a Course
Allow: GET, HEAD, OPTIONS
{
"course_end": "2015-06-30T05:00:00Z",
"course_start": "2015-02-05T05:00:00Z",
"course_id": "edX/DemoX/Demo_Course",
"enrollment_end": null,
"course_modes": [
{
"slug": "honor",
@@ -83,14 +83,11 @@ Get Enrollment Details for a Course
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null,
"sku": null
"description": null
}
],
"enrollment_start": "2015-01-01T05:00:00Z",
"enrollment_end": "2015-02-13T05:00:00Z",
"invite_only": false,
"course_id": "edX/DemoX/Demo_Course"
"enrollment_start": null,
"invite_only": false
}
@@ -103,7 +100,7 @@ View and Add to a User's Course Enrollments
.. autoclass:: enrollment.views.EnrollmentListView
**Example response showing a user's course enrollments**
**Example response showing a user who is enrolled in two courses**
.. code-block:: json
@@ -114,12 +111,12 @@ View and Add to a User's Course Enrollments
[
{
"created": "2014-11-19T04:06:55Z",
"created": "2014-09-19T18:08:37Z",
"mode": "honor",
"is_active": true,
"course_details": {
"course_end": "2015-06-30T05:00:00Z",
"course_start": "2015-02-05T05:00:00Z",
"course_id": "edX/DemoX/Demo_Course",
"enrollment_end": null,
"course_modes": [
{
"slug": "honor",
@@ -128,21 +125,41 @@ View and Add to a User's Course Enrollments
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null,
"sku": null
"description": null
}
],
"enrollment_start": "2015-01-01T05:00:00Z",
"enrollment_end": "2015-02-13T05:00:00Z",
"invite_only": false,
"course_id": "edX/DemoX/Demo_Course"
"enrollment_start": null,
"invite_only": false
},
"user": "honor"
},
"user": "staff"
}
{
"created": "2014-09-19T18:09:35Z",
"mode": "honor",
"is_active": true,
"course_details": {
"course_id": "ArbisoftX/BulkyEmail101/2014-15",
"enrollment_end": null,
"course_modes": [
{
"slug": "honor",
"name": "Honor Code Certificate",
"min_price": 0,
"suggested_prices": [],
"currency": "usd",
"expiration_datetime": null,
"description": null
}
],
"enrollment_start": "2014-05-01T04:00:00Z",
"invite_only": false
},
"user": "honor"
}
]
**Example post request to enroll the user in a new course**
**Example response showing that a user has been enrolled in a new course**
.. code-block:: json

1
docs/en_us/platform_api/source/enrollment/index.rst
View File

@@ -8,5 +8,4 @@ Enrollment API Version 1.0
:maxdepth: 2
overview
endpoints
enrollment

39
docs/en_us/platform_api/source/enrollment/overview.rst
View File

@@ -5,30 +5,45 @@ Enrollment API Overview
################################################
Use the Enrollment API to view user and course enrollment
information, and to enroll a user in a course.
information and to enroll a user in a course.
You can use the Enrollment API for web, desktop, and mobile
applications.
****************************************
Enrollment API Version 1.0
Enrollment API Version and Status
****************************************
The Enrollment API is currently at version 1.0. We plan on making
The Enrollment API is currently at version 1.0. We plan to make
significant enhancements to this API.
********************************************
Enrollment API Capabilities
Enrollment API Endpoints
********************************************
With the Enrollment API, you can complete these tasks.
The Enrollment API supports the following tasks, methods, and endpoints.
* :ref:`Get the user's enrollment status in a course <Get the Users Enrollment
Status in a Course>`
.. list-table::
:widths: 20 10 70
:header-rows: 1
* :ref:`Get enrollment details for a course<Get Enrollment Details for a
Course>`
* - Task
- Method
- Endpoint
* - :ref:`Get the user's enrollment status in a course
<Get the Users Enrollment Status in a Course>`
- GET
- /api/enrollment/v1/enrollment/{user_id},{course_id}
* - :ref:`Get enrollment details for a course
<Get Enrollment Details for a Course>`
- GET
- /api/enrollment/v1/course/{course_id}
* - :ref:`View a user's enrollments
<View and add to a Users Course Enrollments>`
- GET
- /api/enrollment/v1/enrollment
* - :ref:`Enroll a user in a course
<View and add to a Users Course Enrollments>`
- POST
- /api/enrollment/v1/enrollment{“course_details”:{“course_id”:“*course_id*”}}
* :ref:`View a user's enrollments <View and add to a Users Course Enrollments>`
* :ref:`Enroll a user in a course <View and add to a Users Course Enrollments>`

22
docs/en_us/platform_api/source/mobile/course_info.rst
View File

@@ -1,14 +1,12 @@
##################################################
Mobile Course Information API
Mobile Course Information API Resource
##################################################
This page describes how to use the Mobile Course Information API
to complete these actions:
With the Mobile Course Information API resource, you can complete the following tasks.
* `Get Course Updates`_
* `Get Course Handouts`_
* - :ref:`Get updates about a course<Get Course Updates>`.
* - :ref:`Get a list of course handouts<Get Course Handouts>`.
.. _Get Course Updates:
*******************
@@ -50,18 +48,6 @@ Get Course Handouts
.. autoclass:: mobile_api.course_info.views.CourseHandoutsList
**Use Case**
Get the HTML for course handouts.
**Example request**:
``GET /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts``
**Response Values**
* handouts_html: The HTML for course handouts.
**Example response**
.. code-block:: json

31
docs/en_us/platform_api/source/mobile/endpoints.rst
View File

@@ -1,31 +0,0 @@
.. _edX PlatformMobile API Endpoints:
################################################
Mobile API Endpoints
################################################
You use the Mobile API enables to view information about users and
their course enrollments, course information, and videos and transcripts.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Get details about a user<Get User Details>`
- /api/mobile/v0.5/users/{username}
* - :ref:`Get course enrollments for about a user<Get a User's Course Enrollments>`
- /api/mobile/v0.5/users/{username}/course_enrollments/
* - :ref:`Get or change user status in a course<Get or Change User Status in a Course>`
- /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
* - :ref:`Get updates for a course<Get Course Updates>`
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates
* - :ref:`Get handouts for a course<Get Course Handouts>`
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
* - :ref:`Get videos in a course<Get the Video List>`
- /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
* - :ref:`Get a video transcript<Get a Video Transcript>`
- /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}

1
docs/en_us/platform_api/source/mobile/index.rst
View File

@@ -8,7 +8,6 @@ Mobile API Version 0.5
:maxdepth: 2
overview
endpoints
users
course_info
video_outlines

70
docs/en_us/platform_api/source/mobile/overview.rst
View File

@@ -8,7 +8,7 @@ Use the Mobile API to build mobile applications for students to
view course information and videos for courses on your instance of Open edX.
******************************************
Mobile API Version 0.5, Alpha
Mobile API Version and Status
******************************************
The Mobile API is currently at version 0.5 and is an Alpha
@@ -20,19 +20,67 @@ release. We plan on making significant enhancements and changes to the API.
while keeping in mind that endpoints might change.
*************************************
Mobile API Capabilities
Mobile API Resources and Endpoints
*************************************
With the Mobile API, you can complete these tasks.
The Mobile API supports the following resources, tasks, methods, and endpoints.
* Get :ref:`user details<Get User Details>` and :ref:`course enrollments<Get a
User's Course Enrollments>` for a user.
========================
Mobile User API Resource
========================
* :ref:`Get or change user status in a course <Get or Change User Status in a
Course>`
.. list-table::
:widths: 20 10 70
:header-rows: 1
* Get :ref:`updates<Get Course Updates>`, and :ref:`handouts<Get Course
Handouts>` for courses the user is enrolled in.
* - Task
- Method
- Endpoint
* - :ref:`Get details about a user<Get User Details>`
- GET
- /api/mobile/v0.5/users/{username}
* - :ref:`Get course enrollments for a user<Get a User's Course Enrollments>`
- GET
- /api/mobile/v0.5/users/{username}/course_enrollments/
* - :ref:`Get a user's status in a course<Get or Change User Status in a Course>`
- GET
- /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
* - :ref:`Change a user's status in a course<Get or Change User Status in a Course>`
- PATCH
- /api/mobile/v0.5/rs/{username}/course_status_info/{course_id}
* Get :ref:`videos<Get the Video List>` and :ref:`transcripts<Get a Video
Transcript>` for courses the user is enrolled in.
========================================
Mobile Course Information API Resource
========================================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get updates for a course<Get Course Updates>`
- GET
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/updates
* - :ref:`Get handouts for a course<Get Course Handouts>`
- GET
- /api/mobile/v0.5/course_info/{organization}/{course_number}/{course_run}/handouts
=====================================
Mobile Video Outlines API Resource
=====================================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get videos in a course<Get the Video List>`
- GET
- /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
* - :ref:`Get a video transcript<Get a Video Transcript>`
- GET
- /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}

10
docs/en_us/platform_api/source/mobile/users.rst
View File

@@ -2,12 +2,12 @@
Mobile User API
####################################
This page describes how to use the Mobile User API to complete
these actions:
With the Mobile User API resource, you can complete the following tasks.
* `Get User Details`_
* `Get a User's Course Enrollments`_
* `Get or Change User Status in a Course`_
* - :ref:`Get details about a user<Get User Details>`.
* - :ref:`Get course enrollments for a user<Get a User's Course Enrollments>`.
* - :ref:`Get a user's status in a course<Get or Change User Status in a Course>`.
* - :ref:`Change a user's status in a course<Get or Change User Status in a Course>`.
.. _Get User Details:

6
docs/en_us/platform_api/source/mobile/video_outlines.rst
View File

@@ -70,8 +70,4 @@ Get the Video List
Get a Video Transcript
***********************
.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts
**Response Values**
An HttpResponse with an SRT file download.
.. autoclass:: mobile_api.video_outlines.views.VideoTranscripts

21
docs/en_us/platform_api/source/profile_images/endpoints.rst
View File

@@ -1,21 +0,0 @@
################################################
Profile Images API Endpoints
################################################
You use the Profile Images API to upload or remove profile images.
If you have staff access, you can remove profile images from any user
account.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Upload a profile image <Upload a Profile Image>`
- POST /api/profile_images/v1/{username}/upload
* - :ref:`Remove profile images <Remove Profile Images>`
- POST /api/profile_images/v1/{username}/remove

1
docs/en_us/platform_api/source/profile_images/index.rst
View File

@@ -8,5 +8,4 @@ Profile Images API Version 1.0
:maxdepth: 2
overview
endpoints
profile_images

21
docs/en_us/platform_api/source/profile_images/overview.rst
View File

@@ -9,16 +9,27 @@ The requesting user can upload or remove his or her own profile image.
Users with staff access can remove profile images from any user account.
*************************************
Profile Images API Version 1.0
Profile Images API Version and Status
*************************************
The Profile Images API is currently at version 1.0.
**********************************************
Profile Images API Capabilities
Profile Images API Endpoints
**********************************************
With the Profile Images API, you can complete these tasks.
The Profile Images API supports the following tasks, methods, and endpoints.
* :ref:`Upload profile images <Upload a Profile Image>`
* :ref:`Remove profile images <Remove Profile Images>`
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Upload a profile image <Upload a Profile Image>`
- POST
- /api/profile_images/v1/{username}/upload
* - :ref:`Remove a profile image <Remove a Profile Image>`
- POST
- /api/profile_images/v1/{username}/remove

15
docs/en_us/platform_api/source/profile_images/profile_images.rst
View File

@@ -4,11 +4,10 @@
Profile Images API
##################################################
This page contains information on using the Profile Images API to complete
the following actions.
You can use the Profile Images API to complete the following tasks.
* `Upload a Profile Image`_
* `Remove Profile Images`_
* - :ref:`Upload a profile image <Upload a Profile Image>`.
* - :ref:`Remove profile images <Remove a Profile Image>`.
.. _Upload a Profile Image:
@@ -18,7 +17,7 @@ Upload a Profile Image
.. autoclass:: profile_images.views.ProfileImageUploadView
**Example response**
**Example Response**
.. code-block:: json
@@ -26,15 +25,15 @@ Upload a Profile Image
No Content
.. _Remove Profile Images:
.. _Remove a Profile Image:
**************************************************
Remove Profile Images
Remove a Profile Image
**************************************************
.. autoclass:: profile_images.views.ProfileImageRemoveView
**Example response**
**Example Response**
.. code-block:: json

128
docs/en_us/platform_api/source/user/accounts.rst
View File

@@ -15,129 +15,7 @@ complete the following actions.
Get and Update the User's Account Information
**********************************************
.. .. autoclass:: user_api.accounts.views.AccountView
**Use Cases**
Get or update a user's account information. Updates are supported only through
merge patch.
**Example Requests**:
GET /api/user/v1/accounts/{username}/[?view=shared]
PATCH /api/user/v1/accounts/{username}/{"key":"value"} "application/merge-patch+json"
**Response Values for GET**
If the user makes the request for her own account, or makes a request for
another account and has "is_staff" access, the response contains:
* username: The username associated with the account.
* name: The full name of the user.
* email: email for the user (the new email address must be confirmed via a
confirmation email, so GET will not reflect the change until the address has
been confirmed).
* date_joined: The date the account was created, in the string format provided
by datetime. For example, "2014-08-26T17:52:11Z".
* gender: One of the following values:
* "m"
* "f"
* "o"
* null
* year_of_birth: The year the user was born, as an integer, or null.
* level_of_education: One of the following values:
* "p": PhD or Doctorate
* "m": Master's or professional degree
* "b": Bachelor's degree
* "a": Associate's degree
* "hs": Secondary/high school
* "jhs": Junior secondary/junior high/middle school
* "el": Elementary/primary school
* "none": None
* "o": Other
* null: The user did not enter a value.
* language: The user's preferred language, or null.
* country: null (not set), or a Country corresponding to one of the ISO 3166-1
countries.
* country: A ISO 3166 country code or null.
* mailing_address: The textual representation of the user's mailing address, or
null.
* goals: The textual representation of the user's goals, or null.
* bio: null or textural representation of user biographical information ("about
me").
* is_active: boolean representation of whether a user is active.
* profile_image: JSON representation of a user's profile image information. The
keys are: the user's profile image:
* "has_image": boolean indicating whether the user has a profile image.
* "image_url_*": absolute URL to various sizes of a user's profile image, where
'*' matches a representation of the corresponding image size such as 'small',
'medium', 'large', and 'full'. These are configurable via
PROFILE_IMAGE_SIZES_MAP.
* requires_parental_consent: true if the user is a minor requiring parental
consent.
* language_proficiencies: array of language preferences. Each preference is a
JSON object with the following keys:
* "code": string ISO 639-1 language code e.g. "en".
For all text fields, clients rendering the values should take care to HTML
escape them to avoid script injections, as the data is stored
exactly as specified. The intention is that plain text is
supported, not HTML.
If a user who does not have "is_staff" access requests account information for
a different user, only a subset of these fields is returned. The fields
returned depend on the configuration setting ACCOUNT_VISIBILITY_CONFIGURATION,
and the visibility preference of the user for whom data is requested.
Note that a user can view which account fields they have shared with other
users by requesting their own username and providing the url parameter
"view=shared".
If no user exists with the specified username, a 404 error is returned.
**Response Values for PATCH**
Users can only modify their own account information. If the requesting user
does not have username "username", this method will return with a status of 403
for staff access but a 404 for ordinary users to avoid leaking the existence of
the account.
If no user exists with the specified username, a 404 error is returned.
If "application/merge-patch+json" is not the specified content type, a 415
error is returned.
If the update could not be completed due to validation errors, this method
returns a 400 error with all error messages in the "field_errors" field of the
returned JSON.
If the update could not be completed due to a failure at the time of the
update, a 400 error is returned with specific errors in the returned JSON
collection.
If the update is successful, a 204 status is returned with no additional
content.
.. autoclass:: user_api.accounts.views.AccountView
**Example response showing the user's account information**
@@ -153,11 +31,11 @@ content.
"name": "John Doe",
"language": "",
"gender": "m",
"year_of_birth": 2007,
"year_of_birth": 1997,
"level_of_education": "m",
"goals": "Professional Development",
"country": US,
"mailing_address": "406 Highland Ave., Somerville, MA 02144",
"mailing_address": "123 Main Street, Anytown, MA 02144",
"email": "johndoe@company.com",
"date_joined": "2015-03-18T13:42:40Z"
}

36
docs/en_us/platform_api/source/user/endpoints.rst
View File

@@ -1,36 +0,0 @@
################################################
User API Endpoints
################################################
You use the User API to view information about users and update
your own account.
The following tasks and endpoints are currently supported.
.. list-table::
:widths: 10 70
:header-rows: 1
* - To:
- Use this endpoint:
* - :ref:`Get a user's account information <Get and Update the User's
Account Information>`
- GET /api/user/v1/accounts/{username}/[?view=shared]
* - :ref:`Update your account information <Get and Update the User's Account
Information>`
- PATCH /api/user/v1/accounts/{username}/{“key”:”value”}
* - :ref:`Get a user's preferences information <Get and Update the User's
Preferences Information>`
- GET /api/user/v1/preferences/{username}/
* - :ref:`Update a user's preferences information <Get and Update the User's
Preferences Information>`
- PATCH /api/user/v1/preferences/{username}/
* - :ref:`Get a specific preference <Get Update or Delete a Specific
Preference>`
- GET /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Update a specific preference <Get Update or Delete a Specific
Preference>`
- PUT /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Delete a specific preference <Get Update or Delete a Specific
Preference>`
- DELETE /api/user/v1/preferences/{username}/{preference_key}

1
docs/en_us/platform_api/source/user/index.rst
View File

@@ -8,6 +8,5 @@ User API Version 1.0
:maxdepth: 2
overview
endpoints
accounts
preferences

64
docs/en_us/platform_api/source/user/overview.rst
View File

@@ -7,21 +7,67 @@ Use the User API to view and update account and preference information.
You can use the User API for web, desktop, and mobile applications.
*************************************
User API Version 1.0
User API Version and Status
*************************************
The User API is currently at version 1.0. We plan on making
significant enhancements to this API.
**********************************************
User API Capabilities
User API Resources and Endpoints
**********************************************
With the User API, you can complete these tasks.
The User API supports the following resources, tasks, methods, and endpoints.
* :ref:`Get and update the users' account information <Get and Update the
User's Account Information>`
* :ref:`Get and update the user's preferences information <Get and Update the
User's Preferences Information>`
* :ref:`Get, update or delete a specific preference: <Get Update or Delete a
Specific Preference>`
=============================
User Accounts API Resource
=============================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get a user's account information <Get and Update the User's
Account Information>`
- GET
- /api/user/v1/accounts/{username}/[?view=shared]
* - :ref:`Update your account information <Get and Update the User's Account
Information>`
- PATCH
- /api/user/v1/accounts/{username}/{“key”:”value”}
=============================
User Preferences API Resource
=============================
.. list-table::
:widths: 20 10 70
:header-rows: 1
* - Task
- Method
- Endpoint
* - :ref:`Get a user's preferences information
<Get and Update the User's Preferences Information>`
- GET
- /api/user/v1/preferences/{username}/
* - :ref:`Update a user's preferences information
<Get and Update the User's Preferences Information>`
- PATCH
- /api/user/v1/preferences/{username}/
* - :ref:`Get a specific preference
<Get Update or Delete a Specific Preference>`
- GET
- /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Update a specific preference
<Get Update or Delete a Specific Preference>`
- PUT
- /api/user/v1/preferences/{username}/{preference_key}
* - :ref:`Delete a specific preference
<Get Update or Delete a Specific Preference>`
- DELETE
- /api/user/v1/preferences/{username}/{preference_key}