Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Orion/Server API/User API"

m
(→‎Read the user list)
 
(20 intermediate revisions by one other user not shown)
Line 3: Line 3:
 
== Actions on users ==
 
== Actions on users ==
  
−
=== Creating users ===
+
=== Can create users ===
  
 
{{Orion/ServerAPI
 
{{Orion/ServerAPI
−
| overview = Overview
 
 
| method = POST
 
| method = POST
 +
| overview = Before creating a new user account, send a POST request to determine if you can create new user accounts on this server.
 +
| reqhead = /useremailconfirmation/cansendemails HTTP/1.1
 +
Orion-Version: 1.0
 +
| resphead = 200 OK
 +
Content-Type: application/json
 +
| respbody = 
 +
{
 +
  "CanAddUsers":true,
 +
  "ForceEmail":true
 +
  }
 +
| explain = If CanAddUsers is true then only system administrators can create user accounts. If ForceEmail is true then the user account must provide an email address in addition to username and password. This API is normally queried before adding special UI to the main page (i.e. adding a create user capability).
 +
}}
 +
 +
=== Create a user ===
 +
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To create a new user account, send a POST request with the UserName and Password.
 
| reqhead = /users HTTP/1.1
 
| reqhead = /users HTTP/1.1
 
  Orion-Version: 1.0
 
  Orion-Version: 1.0
 
  Content-Type: application/json
 
  Content-Type: application/json
 
| reqbody = {
 
| reqbody = {
−
   "Login" : "Login",
+
   "UserName" : "newuser",
−
   "Password" : "Password"
+
   "Password" : "newPassw0rd"
 +
  "FullName": "New User",
 
  }
 
  }
−
| resphead = 201 OK
+
| resphead = 201 CREATED
−
| respbody = {
+
Content-Type: application/json
−
   "Login" : "Login"
+
| respbody =  
 +
{
 +
   "EmailConfirmed": false,
 +
  "FullName": "New User",
 +
  "HasPassword": true,
 +
  "Location": "/users/newuser",
 +
  "UserName": "newuser"
 
  }
 
  }
−
| explain = TBD.
+
| explain = FullName and Email are optional fields that can be added to the request. The request does not need to be authenticated unless the server specifies that only the admin users can create accounts.
 
}}
 
}}
  
−
=== Getting a user ===
+
=== Read a user ===
  
−
=== Updating a user ===
+
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = To read a user account profile, send a GET request.
 +
| reqhead = /users/newuser HTTP/1.1
 +
Orion-Version: 1.0
 +
| resphead = 200 OK
 +
Content-Type: application/json
 +
| respbody =  
 +
{
 +
  "EmailConfirmed": false,
 +
  "FullName": "New User",
 +
  "HasPassword": true,
 +
  "Location": "/users/newuser",
 +
  "UserName": "newuser"
 +
}
 +
| explain = The request needs to be authenticated as newuser or an admin user.
 +
}}
  
−
=== Deleting a user ===
+
=== Update a user ===
  
−
=== Listing users ===
+
{{Orion/ServerAPI
 +
| method = PUT
 +
| overview = To update a user account, send a PUT request with the updated properties.
 +
| reqhead = /users/newuser HTTP/1.1
 +
Orion-Version: 1.0
 +
Content-Type: application/json
 +
| reqbody = {
 +
  "Password" : "oldPassw0rd"
 +
  "NewPassword" : "newPassw0rd"
 +
  "FullName": "New Full Name",
 +
}
 +
| resphead = 200 OK
 +
| explain = Users other than admin have to provide the old password to set a new one.
 +
}}
  
−
== Actions on user roles ==
+
=== Delete a user ===
  
−
= JSON representations =
+
{{Orion/ServerAPI
 +
| method = DELETE
 +
| overview = To delete a user account profile, send a DELETE request.
 +
| reqhead = /users/newuser HTTP/1.1
 +
Orion-Version: 1.0
 +
| resphead = 200 OK
 +
| explain = The request needs to be authenticated as newuser or an admin user.
 +
}}
 +
 
 +
=== Read the user list ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = GET
 +
| overview = An admin user can use the users API to get a user account list by sending a GET request.
 +
| reqhead = /users?start=0&rows=3 HTTP/1.1
 +
Orion-Version: 1.0
 +
| resphead = 200 OK
 +
Content-Type: application/json
 +
| respbody =  { "Users": [
 +
    {
 +
      "DiskUsage": "16K",
 +
      "DiskUsageTimestamp": "1416434105405",
 +
      "Email": "user@somewhere.com",
 +
      "EmailConfirmed": true,
 +
      "FullName": "User Account",
 +
      "HasPassword": true,
 +
      "LastLoginTimestamp": "1416414407369",
 +
      "Location": "/users/account",
 +
      "UserName": "account"
 +
    },
 +
    {
 +
      "DiskUsage": "32K",
 +
      "DiskUsageTimestamp": "1416434105487",
 +
      "EmailConfirmed": false,
 +
      "FullName": "Administrative User",
 +
      "HasPassword": true,
 +
      "LastLoginTimestamp": "1416435479931",
 +
      "Location": "/users/admin",
 +
      "UserName": "admin"
 +
    },
 +
    {
 +
      "DiskUsage": "56K",
 +
      "DiskUsageTimestamp": "1416434105438",
 +
      "FullName": "Another User",
 +
      "HasPassword": true,
 +
      "LastLoginTimestamp": "1416434593638",
 +
      "Location": "/users/anotheruser",
 +
      "UserName": "anotheruser"
 +
    }
 +
  ],
 +
{
 +
  "UsersLength": 1956,
 +
  "UsersRows": 3,
 +
  "UsersStart": 0
 +
  }
 +
| explain = The user must be authenticated as an admin user to access this API. The users are returned in order by UserName. The users_length specifies the number of users in the server workspace. If there is no start parameter the list is returned starting with the first user. If there is no end parameter the default is to return 20 rows. If there is neither start or rows parameters the first 20 users are returned.
 +
}}
 +
 
 +
== Actions on user password and email ==
 +
 
 +
=== Can send emails ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = Before requesting a user account password reset, send a POST request to determine if you can sent password reset notifications on this server.
 +
| reqhead = /useremailconfirmation/cansendemails HTTP/1.1
 +
Orion-Version: 1.0
 +
| resphead = 200 OK
 +
Content-Type: application/json
 +
| respbody =  {
 +
  "EmailConfigured": true
 +
  }
 +
| explain = The request does need to be authenticated.
 +
}}
 +
 
 +
=== Request password reset ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To request a password reset, send a POST request with either the UserName or Email for the user account. An email notification is sent that starts the password reset process.
 +
| reqhead = /useremailconfirmation HTTP/1.1
 +
Orion-Version: 1.0
 +
Content-Type: application/json
 +
| reqbody = {
 +
  "UserName" : "newuser",
 +
  "Email": "newuser@somewhere.com",
 +
}
 +
| resphead = 200 OK
 +
| explain = If both UserName and Email are provided, only the UserName is used to reset the account.
 +
}}
 +
 
 +
=== Change password ===
 +
 
 +
{{Orion/ServerAPI
 +
| method = POST
 +
| overview = To change the password for a user account, send a POST request against the UserName and provide the new Password.
 +
| reqhead = /users/newuser HTTP/1.1
 +
Orion-Version: 1.0
 +
Content-Type: application/json
 +
| reqbody = {
 +
  "Password" : "newPassw0rd"
 +
  "Reset": true,
 +
}
 +
| resphead = 200 OK
 +
| explain = The request needs to be authenticated and only an admin account or the account owner can reset their password.
 +
}}
  
−
== User ==
 
  
 
[[Category:Orion/API|User]]
 
[[Category:Orion/API|User]]
 
[[Category:Orion/Server API|User]]
 
[[Category:Orion/Server API|User]]

Latest revision as of 18:21, 24 November 2014

The User API is a web server API for browsing and manipulating users.

Actions on users

Can create users

Overview
Before creating a new user account, send a POST request to determine if you can create new user accounts on this server.
HTTP Method
POST
Example Request
POST /useremailconfirmation/cansendemails HTTP/1.1
Orion-Version: 1.0
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "CanAddUsers":true,
 "ForceEmail":true
 }
Detailed Explanation
If CanAddUsers is true then only system administrators can create user accounts. If ForceEmail is true then the user account must provide an email address in addition to username and password. This API is normally queried before adding special UI to the main page (i.e. adding a create user capability).


Create a user

Overview
To create a new user account, send a POST request with the UserName and Password.
HTTP Method
POST
Example Request
POST /users HTTP/1.1
Orion-Version: 1.0
Content-Type: application/json

{
 "UserName" : "newuser",
 "Password" : "newPassw0rd"
 "FullName": "New User",
}
Example Response
HTTP/1.1 201 CREATED
Content-Type: application/json

{
 "EmailConfirmed": false,
 "FullName": "New User",
 "HasPassword": true,
 "Location": "/users/newuser",
 "UserName": "newuser"
}
Detailed Explanation
FullName and Email are optional fields that can be added to the request. The request does not need to be authenticated unless the server specifies that only the admin users can create accounts.


Read a user

Overview
To read a user account profile, send a GET request.
HTTP Method
GET
Example Request
GET /users/newuser HTTP/1.1
Orion-Version: 1.0
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "EmailConfirmed": false,
 "FullName": "New User",
 "HasPassword": true,
 "Location": "/users/newuser",
 "UserName": "newuser"
}
Detailed Explanation
The request needs to be authenticated as newuser or an admin user.


Update a user

Overview
To update a user account, send a PUT request with the updated properties.
HTTP Method
PUT
Example Request
PUT /users/newuser HTTP/1.1
Orion-Version: 1.0
Content-Type: application/json

{
 "Password" : "oldPassw0rd"
 "NewPassword" : "newPassw0rd"
 "FullName": "New Full Name",
}
Example Response
HTTP/1.1 200 OK
Detailed Explanation
Users other than admin have to provide the old password to set a new one.


Delete a user

Overview
To delete a user account profile, send a DELETE request.
HTTP Method
DELETE
Example Request
DELETE /users/newuser HTTP/1.1
Orion-Version: 1.0
Example Response
HTTP/1.1 200 OK
Detailed Explanation
The request needs to be authenticated as newuser or an admin user.


Read the user list

Overview
An admin user can use the users API to get a user account list by sending a GET request.
HTTP Method
GET
Example Request
GET /users?start=0&rows=3 HTTP/1.1
Orion-Version: 1.0
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{ "Users": [
   {
     "DiskUsage": "16K",
     "DiskUsageTimestamp": "1416434105405",
     "Email": "user@somewhere.com",
     "EmailConfirmed": true,
     "FullName": "User Account",
     "HasPassword": true,
     "LastLoginTimestamp": "1416414407369",
     "Location": "/users/account",
     "UserName": "account"
   },
   {
     "DiskUsage": "32K",
     "DiskUsageTimestamp": "1416434105487",
     "EmailConfirmed": false,
     "FullName": "Administrative User",
     "HasPassword": true,
     "LastLoginTimestamp": "1416435479931",
     "Location": "/users/admin",
     "UserName": "admin"
   },
   {
     "DiskUsage": "56K",
     "DiskUsageTimestamp": "1416434105438",
     "FullName": "Another User",
     "HasPassword": true,
     "LastLoginTimestamp": "1416434593638",
     "Location": "/users/anotheruser",
     "UserName": "anotheruser"
   }
 ],
{
 "UsersLength": 1956,
 "UsersRows": 3,
 "UsersStart": 0
 }
Detailed Explanation
The user must be authenticated as an admin user to access this API. The users are returned in order by UserName. The users_length specifies the number of users in the server workspace. If there is no start parameter the list is returned starting with the first user. If there is no end parameter the default is to return 20 rows. If there is neither start or rows parameters the first 20 users are returned.


Actions on user password and email

Can send emails

Overview
Before requesting a user account password reset, send a POST request to determine if you can sent password reset notifications on this server.
HTTP Method
POST
Example Request
POST /useremailconfirmation/cansendemails HTTP/1.1
Orion-Version: 1.0
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "EmailConfigured": true
 }
Detailed Explanation
The request does need to be authenticated.


Request password reset

Overview
To request a password reset, send a POST request with either the UserName or Email for the user account. An email notification is sent that starts the password reset process.
HTTP Method
POST
Example Request
POST /useremailconfirmation HTTP/1.1
Orion-Version: 1.0
Content-Type: application/json

{
 "UserName" : "newuser",
 "Email": "newuser@somewhere.com",
}
Example Response
HTTP/1.1 200 OK
Detailed Explanation
If both UserName and Email are provided, only the UserName is used to reset the account.


Change password

Overview
To change the password for a user account, send a POST request against the UserName and provide the new Password.
HTTP Method
POST
Example Request
POST /users/newuser HTTP/1.1
Orion-Version: 1.0
Content-Type: application/json

{
 "Password" : "newPassw0rd"
 "Reset": true,
}
Example Response
HTTP/1.1 200 OK
Detailed Explanation
The request needs to be authenticated and only an admin account or the account owner can reset their password.
Retrieved from "https://wiki.eclipse.org/index.php?title=Orion/Server_API/User_API&oldid=374189"

This page was last modified 18:21, 24 November 2014 by Anthony Hunter. Based on work by Mark Macdonald and Szymon Brandys.

Back to the top