Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Add Documentation for User Endpoints #158

Merged
merged 7 commits into from

2 participants

Rachel Baker Ryan McCue
Rachel Baker
Owner

Now that #146 is merged, we need to add user handling into our existing documentation.

Rachel Baker rachelbaker added this to the 1.0 milestone
Rachel Baker
Owner

@rmccue #reviewmerge

Ryan McCue rmccue was assigned by rachelbaker
docs/routes/users.md
((22 lines not shown))
+ Default is "user_login". (string)
+* `order` - Order to sort by. Default is "ASC". (string, "ASC" or "DESC")
+* `s` - Keyword to search for. (string)
+
+### Response
+The response is a User Collection document containing the requested Users if
+available.
+
+
+Retrieve Current User
+-------------
+
+ GET /users/me
+
+### Input
+#### `fields`
Ryan McCue Owner
rmccue added a note

This is a holdover from the very old /posts/<id> endpoint; should now be context instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/routes/users.md
((106 lines not shown))
+Delete a User
+-------------
+
+ DELETE /users/<id>
+
+### Input
+#### `force`
+The `force` parameter controls whether the user is permanently deleted or not.
+By default, this is set to false, indicating that the user will be sent to an
+intermediate storage (such as the trash) allowing it to be restored later. If
+set to true, the user will not be able to be restored.
+
+Default is false. (boolean)
+
+#### `reassign`
+The `reassign` parameter controls whether the deleted user's content is reassigned to a new User or not. By default, this is set to null, indicating that the deleted user's content will not be reassigned.
Ryan McCue Owner
rmccue added a note

Lines should be wrapped to 80 characters (except for URLs/etc that don't make sense wrapped).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Ryan McCue
Owner

@rachelbaker #reviewmerge :)

Ryan McCue rmccue removed their assignment
Rachel Baker rachelbaker was assigned by rmccue
Rachel Baker rachelbaker merged commit c3923c9 into from
Rachel Baker rachelbaker deleted the branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 159 additions and 0 deletions.
  1. +159 −0 docs/routes/users.md
159 docs/routes/users.md
View
@@ -0,0 +1,159 @@
+Users
+=====
+
+Retrieve Users
+--------------
+The Users endpoint returns a User Collection containing a subset of the site's
+users.
+
+ GET /users
+
+### Input
+#### `filter`
+The `filter` parameter controls the query parameters. It is essentially a subset
+of the parameters available to [`WP_User_Query`](http://codex.wordpress.org/Class_Reference/WP_User_Query).
+
+The parameter should be an array of the following key/value pairs:
+
+* `number` - Number of users to retrieve, use `-1` for all users. Default
+ is set by the site. (integer)
+* `offset` - Number of posts to skip. Default is 0. (integer)
+* `orderby` - Parameter to search by, as per [`WP_User_Query`](https://codex.wordpress.org/Class_Reference/WP_User_Query#Order_.26_Orderby_Parameters).
+ Default is "user_login". (string)
+* `order` - Order to sort by. Default is "ASC". (string, "ASC" or "DESC")
+* `s` - Keyword to search for. (string)
+
+### Response
+The response is a User Collection document containing the requested Users if
+available.
+
+
+Create a User
+-------------
+
+ POST /users
+
+### Input
+The supplied data should be a User object. This data can be submitted via a
+regular HTTP multipart body, with User values set as values to the `data`
+parameter, or through a direct JSON body.
+
+That is, the following are equivalent:
+
+Content-Type: application/x-www-form-urlencoded
+
+ data[username]=newuser&data[name]=New%20User&data[password]=secret
+
+
+Content-Type: application/json
+
+ {"username":"newuser","name":"New User","password":"secret"}
+
+### Response
+On a successful creation, a 201 Created status is given, indicating that the
+user has been created. The user is available canonically from the URL specified
+in the Location header.
+
+The new User entity is also returned in the body for convienience.
+
+
+Retrieve a User
+---------------
+
+ GET /users/<id>
+
+### Input
+#### `context`
+The `context` parameter controls the format of the data to return. The following
+contexts are available:
+
+* `view`: The default context. Gives the normal User entity.
+* `edit`: Context used for extra fields relevant to updating a user. Includes
+ the `extra_capabilities` field; this field contains the capabilities assigned
+ to the user themselves, rather than those inherited from their roles.
+* `embed`: Context used when embedding the response inside another (e.g. post
+ author). This is intended as a minimal subset of the user data to reduce
+ response size. Excludes `roles` and `capabilities`.
+
+Default is "view". (string)
+
+### Response
+The response is a User entity containing the requested User if available. The
+fields available on the User depend on the `context` parameter.
+
+
+Retrieve Current User
+-------------
+
+ GET /users/me
+
+This endpoint offers a permalink to get the current user, without needing to
+know the user's ID.
+
+### Input
+#### `context`
+The `context` parameter controls the format of the data to return. See the
+Retrieve a User endpoint for available contexts.
+
+Default is "view". (string)
+
+### Response
+If the client is currently logged in, a 302 Found status is given. The User is
+available canonically from the URL specified in the Location header.
+
+The User entity containing the current User is also returned in the body for
+convenience. The fields available on the User depend on the `context` parameter.
+
+If the client is not logged in, a 401 Unauthorized status is given.
+
+
+Edit a User
+-----------
+
+ PUT /users/<id>
+
+For compatibility reasons, this endpoint also accepts the POST and PATCH
+methods. Both of these methods have the same behaviour as using PUT. It is
+recommended to use PUT if available to fit with REST convention.
+
+### Input
+The supplied data should be a User object. This data can be submitted via a
+regular HTTP multipart body, with User values set as values to the `data`
+parameter, or through a direct JSON body. See the Create User endpoint for an
+example.
+
+### Response
+On a successful update, a 200 OK status is given, indicating the user has been
+updated. The updated User entity is returned in the body.
+
+
+Delete a User
+-------------
+
+ DELETE /users/<id>
+
+### Input
+#### `force`
+The `force` parameter controls whether the user is permanently deleted or not.
+By default, this is set to false, indicating that the user will be sent to an
+intermediate storage (such as the trash) allowing it to be restored later. If
+set to true, the user will not be able to be restored.
+
+Default is false. (boolean)
+
+#### `reassign`
+The `reassign` parameter controls whether the deleted user's content is
+reassigned to a new User or not. If set to `null`, the deleted user's content
+will not be reassigned.
+
+Default is null. (integer)
+
+
+### Response
+On successful deletion, a 202 Accepted status code will be returned, indicating
+that the user has been moved to the trash for permanent deletion at a
+later date.
+
+If force was set to true, a 200 OK status code will be returned instead,
+indicating that the user has been permanently deleted.
+
Something went wrong with that request. Please try again.