BuddyPress/buddypress
1
0
Fork 0
mirror of https://github.com/buddypress/buddypress.git synced 2026-07-23 21:06:56 +08:00
Code Packages Activity Actions
buddypress/docs/developer/execution-contexts/rest-api/members.md
Mathieu Viet 00eb574c81 Documentation: start documenting v2 of the BP REST API 
Add the following page to developer doc:
- Introduction about the BP REST API
- Reference: list of REST API Routes
- Components routes
- Members routes

NB: this commit also improves Components and Members REST controllers item schemas.

See https://buddypress.trac.wordpress.org/ticket/9145
Closes https://github.com/buddypress/buddypress/pull/382



git-svn-id: https://buddypress.svn.wordpress.org/trunk@14042 cdf35c40-ae34-48e0-9cc9-0c9da1808c22
2024-10-09 04:36:10 +00:00

15 KiB
Raw Permalink Blame History

Members REST API routes

The BuddyPress Members REST controller extends the WordPress Users one to include specific BuddyPress data such as profile fields data1 and use the BP_User_Query instead of the WP_User_Query to fetch the members.

Schema

The schema defines all the fields that exist for a member object.

Property Description
id Unique identifier for the member.
JSON data type: integer.
Read only.
Context: embed, view, edit.
name Display name for the member.
JSON data type: string.
Context: embed, view, edit.
mention_name The name used for that user in @-mentions.
JSON data type: string.
Context: embed, view, edit.
link Profile URL of the member.
JSON data type: string, format: URI.
Read only.
Context: embed, view, edit.
user_login An alphanumeric identifier for the member.
JSON data type: string.
Context: embed, view, edit.
member_types Member types associated with the member. See this documentation page for more information.
JSON data type: array.
Read only.
Context: embed, view, edit.
registered_date Registration date for the member.
JSON data type: string | null, format: date-time.
Read only.
Context: edit.
registered_date_gmt The date the member was registered, as GMT.
JSON data type: string | null, format: date-time.
Read only.
Context: edit.
registered_since Elapsed time since the member registered.
JSON data type: string.
Read only.
Context: view, edit.
password Password for the member (never included).
JSON data type: string.
Context: none.
roles Roles assigned to the member.
JSON data type: array.
Context: edit.
capabilities All capabilities assigned to the member.
JSON data type: object.
Read only.
Context: edit.
capabilities Any extra capabilities assigned to the user.
JSON data type: object.
Read only.
Context: edit.
xprofile2 Member xProfile groups and its fields.
JSON data type: array.
Read only.
Context: view, edit.
friendship_status3 Whether the logged in user has a friendship relationship with the fetched user.
JSON data type: boolean.
Read only.
Context: view, edit.
friendship_status_slug3 Slug of the friendship relationship status the logged in user has with the fetched user.
JSON data type: string.
Read only.
One of: is_friend, not_friends, pending, awaiting_response.
Context: view, edit.
total_friend_count3 Total number of friends for the member.
JSON data type: integer.
Read only.
Context: view, edit.
last_activity Last date the member was active on the site.
JSON data type: object (properties: timediff, date and date_gmt).
Read only.
Context: view, edit.
latest_update4 The content of the latest activity posted by the member.
JSON data type: object (properties: id, raw and rendered).
Read only.
Context: view, edit.
avatar_urls5 Avatar URLs for the member (Full & Thumb sizes).
JSON data type: object (properties: full, and thumb).
Read only.
Context: embed, view, edit.

List Members

Arguments

Name Description
context Scope under which the request is made; determines fields present in response.
JSON data type: string.
Default: view.
One of: view, embed, edit.
page Current page of the collection.
JSON data type: integer.
Default: 1.
per_page Maximum number of members to be returned in result set.
JSON data type: integer.
Default: 10.
search Limit results to those matching a string.
JSON data type: string.
exclude Ensure result set excludes specific IDs.
JSON data type: array.
Default: [].
include Ensure result set includes specific IDs.
JSON data type: array.
Default: [].
type Shorthand for certain orderby/order combinations.
JSON data type: string.
Default: newest.
One of: active, newest, alphabetical, random, online, popular.
user_id Limit results to friends of a user.
JSON data type: integer.
Default: 0.
user_ids Pass IDs of users to limit result set.
JSON data type: array.
Default: [].
populate_extras Whether to fetch extra BP data about the returned members.
JSON data type: boolean.
Default: false.
member_type Limit results set to certain type(s). See this documentation page for more information.
JSON data type: array.
Default: [].
xprofile Limit results set to a certain xProfile field.
JSON data type: array.
Default: [].

Definition

GET /buddypress/v2/members

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members?context=view&type=active', {
	method: 'GET',
	headers: requestHeaders,
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.table( data );
} );

JSON Response

  • An array of objects representing the matching members on success.
  • An object containg the error code, data and message on failure.

Create a member

Only users having the create_users WordPress capability can create a new member.

Arguments

Name Description
user_login An alphanumeric identifier for the member. Required.
JSON data type: string.
password Password for the member. Required.
JSON data type: string.
email The email address for the member. Required.
JSON data type: string.
name Display name for the member.
JSON data type: string.
roles Roles assigned to the member.
JSON data type: array.
member_type A comma separated list of Member Types to set for the member. See this documentation page for more information.
JSON data type: string.

Definition

POST /buddypress/v2/members

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members', {
	method: 'POST',
	headers: requestHeaders,
	body: JSON.stringify(
		{
			'user_login': 'bapuu',
			password: 'neverUseWe@kPassW0rd!',
			email: 'bapuu@buddypress.org',
			name: 'Bapuu',
		}
	),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the created member on success.
  • An object containg the error code, data and message on failure.

Retrieve a specific member

Arguments

Name Description
id Unique identifier for the member. Required.
JSON data type: integer.
context Scope under which the request is made; determines fields present in response.
JSON data type: string.
Default: view.
One of: view, embed, edit.
populate_extras Whether to fetch extra BP data about the returned member.
JSON data type: boolean.
Default: false.

Definition

GET /buddypress/v2/members/<id>

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members/2?populate_extras=true', {
	method: 'GET',
	headers: requestHeaders,
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the member on success.
  • An object containg the error code, data and message on failure.

Update a specific member

Arguments

Name Description
id Unique identifier for the user. Required.
JSON data type: integer.
name Display name for the member.
JSON data type: string.
roles Roles assigned to the member.
JSON data type: array.
member_type A comma separated list of Member Types to set for the member. See this documentation page for more information.
JSON data type: string.

Definition

PUT /buddypress/v2/members/<id>

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members/2', {
	method: 'PUT',
	headers: requestHeaders,
	body: JSON.stringify( { name: 'Bapuu The BP Wapuu' } ),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the updated member on success.
  • An object containg the error code, data and message on failure.

Delete a specific member

Arguments

Name Description
id Unique identifier for the user. Required.
JSON data type: integer.
force Required to be true, as members do not support trashing. Required.
JSON data type: boolean.
Default: false.
reassign Reassign the deleted member’s posts and links to this user ID. Required.
JSON data type: integer.

Definition

DELETE /buddypress/v2/members/<id>

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members/2', {
	method: 'DELETE',
	headers: requestHeaders,
	body: JSON.stringify(
		{
			force: true,
			reassign: 1,
		}
	),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object informing about the deleted status and the previous member on success.
  • An object containg the error code, data and message on failure.

Retrieve the logged in member

Arguments

Name Description
context Scope under which the request is made; determines fields present in response.
JSON data type: string.
Default: view.
One of: view, embed, edit.
populate_extras Whether to fetch extra BP data about the returned member.
JSON data type: boolean.
Default: false.

Definition

GET /buddypress/v2/members/me

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members/me', {
	method: 'GET',
	headers: requestHeaders,
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the member on success.
  • An object containg the error code, data and message on failure.

Update the logged in member

To update roles, the logged in member must have the_ promote_user capability.

Arguments

Name Description
name Display name for the member.
JSON data type: string.
roles Roles assigned to the member.
JSON data type: array.
member_type A comma separated list of Member Types to set for the member. See this documentation page for more information.
JSON data type: string.

Definition

PUT /buddypress/v2/members/me

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members/me', {
	method: 'PUT',
	headers: requestHeaders,
	body: JSON.stringify( { name: 'Admin Istrator' } ),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object representing the updated member on success.
  • An object containg the error code, data and message on failure.

Delete the logged in member

Arguments

Name Description
force Required to be true, as members do not support trashing. Required.
JSON data type: boolean.
Default: false.
reassign Reassign the deleted member’s posts and links to this user ID. Required.
JSON data type: integer.

Definition

DELETE /buddypress/v2/members/me

Example of use

Warning

The requestHeaders object needs to be set according to the WordPress REST API nonce. Read more about the REST API authentification.

fetch( '/wp-json/buddypress/v2/members/me', {
	method: 'DELETE',
	headers: requestHeaders,
	body: JSON.stringify(
		{
			force: true,
			reassign: 1,
		}
	),
} ).then( ( response ) => {
	return response.json();
} ).then( ( data ) => {
	 console.log( data );
} );

JSON Response

  • An object informing about the deleted status and the previous member on success.
  • An object containg the error code, data and message on failure.

  1. the eXtended Profiles component needs to be active on the website to make these profile fields available into Members REST requests. ↩︎

  2. data is only fetched if the eXtended Profiles component is active. ↩︎

  3. data is only fetched if the Friends component is active. ↩︎

  4. data is only fetched if the Activity component is active. ↩︎

  5. This property is only available if the WordPress discussion settings allow avatars. ↩︎