-
Notifications
You must be signed in to change notification settings - Fork 0
REST API
- Path Parameters are parameters directly available in the path ie in /user/:name, the name is a path parameter
- Query Parameters are parameters available in the query part ie /user?login=foo&name=bar has two query paramaters (login and name)
If an error occurs on the server side or if a resource can not be found (the specified user can not be found), the client will receive an HTTP Error 400. As an error message, the following JSON payload will be returned:
{
"message":"The error message",
"errors":[
{
"code":"Error code",
"resource":"...",
"field":"..."
}
]
}
The REST API is protected using OAuth2 mechanisms. On each request received by the governance service, the implementation will authenticate and authorize user to access to resources.
In the current version, we use a OAuth2 bearer token for all resources described below: Each HTTP request must contain a valid authorization header like:
Authorization: Bearer 1234567890
Where 1234567890 is a token used to retrieve right credentials.
Note: For now, the token is fixed and defined in the governance-war project in the governance-war/src/main/webapp/WEB-INF/rest.xml file.
The User API is defined in governance-user-api/org.ow2.play.governance.user.api.rest.UserService. It provides methods to register, update, search and delete user from the system.
A user resource contains:
- login
- password
- avatarURL
- fullName
- accounts : An array of Accounts. Accounts are external providers information such as Twitter or Facebook which can be used to login to the Play Platform if the user has connected them using the account management application. Account are defined like:
- login
- provider: The provider name (twitter, facebook, github, ...)
- token: OAuth1 token (if applicable based on the provider)
- secret: OAuth1 secret (if applicable based on the provider)
- accessToken: OAuth2 access_token (if applicable based on the provider)
- fullName
- avatarURL
- groups: A list of groups the user belongs to
- resources: A list of resources the user created in the platform. It can be subscriptions, patterns he deployed, ... All these resources are links to real resources in the governance service.
Get user information from its unique ID.
GET /users/:id
or get user from its login
GET /users/login/:login
HTTP Code 200 - OK
{
"login":"chamerling",
"password":"...",
"accounts":[
{
"provider":"twitter",
"login":"chamerling"
},
{
"provider":"google",
"login":"ham"
}
]
}
Search a single user from its provider login and provider type
GET /users/query
- login: The login used in the given provider
- provider: The provider name (twitter, google, github, ...)
HTTP Code 200 - OK
{
"login":"chamerling",
"password":"...",
"accounts":[
{
"provider":"twitter",
"login":"chamerling"
},
{
"provider":"google",
"login":"ham"
}
]
}
Register a new user in the system.
TODO : Secure it! As REST API, we must protect this method with management credentials.
POST /users
- login required string
- password required string. Will be hashed by the backend.
- email optional string
- avatarURL optional string
- accounts optional array of accounts
{
"login":"chamerling",
"password":"...",
"accounts":[
{
"provider":"twitter",
"login":"chamerling"
},
{
"provider":"google",
"login":"ham"
}
]
}
HTTP Code 201 - Created
{
"id":"1234567890"
"login":"chamerling",
"password":"",
"accounts":[
{
"provider":"twitter",
"login":"chamerling"
},
{
"provider":"google",
"login":"ham"
}
]
}
Notes:
- This will return a user instance with its ID.
- Password is hashed in the backend.
Deprecated
Update user information. Note that for now, password update is not provided in the API, as well as user ID. All the other information can be updated by sending a user message.
PUT /users
- login required string : Will be used to identify theuser to update...
- password required string
- All other information to update can be set in the user payload
Note that for now, the service does not compare input and persisted accounts. It will override existing ones with the input ones i.e. if you want to update accounts, it will be nice to fetch them before...
{
"login":"chamerling",
"password":"...",
"email":"[email protected]",
"accounts":[
{
"provider":"twitter",
"login":"chamerling"
},
{
"provider":"google",
"login":"ham"
},
{
"provider":"github",
"login":"chamerling"
}
]
}
HTTP Code 200 - OK
{
"login":"chamerling",
"password":"",
"email":"[email protected]",
"accounts":[
{
"provider":"twitter",
"login":"chamerling"
},
{
"provider":"google",
"login":"ham"
},
{
"provider":"github",
"login":"chamerling"
}
]
}
Accounts are external accounts on OAuth providers (Twitter, FB, Github, Google, ...). If the user linked its Play account with an external provider, it will be able to log in to the platform using its external credentials.
GET /users/:id/accounts
Returns the user accounts list as JSON array
HTTP 200 - OK
[
{
"provider":"twitter",
"login":"chamerling"
},
{
"provider":"google",
"login":"ham"
},
{
"provider":"github",
"login":"chamerling"
}
]
POST /users/:id/accounts
With Account as input in JSON.
{
"provider":"github",
"login":"chamerling",
"XXX" : "YYY"
}
Returns the updated user.
HTTP 200 - OK
Delete an account from a given provider in the current user accounts list:
DELETE /users/:id/accounts
- Query Parameter: provider.
- Query Parameter: username
Returns
HTTP 204 - No content
Resources are links to platform resources the user subscribed, deployed, ...
GET /users/:id/resources
Returns a resource list as JSON resource array:
HTTP 200 - OK
[
{
name: "pattern",
uri: "http://pattern.play.org/foo
},
{
name: "subscription",
uri: "http://subscriptions.play.org/bar
}
]
POST /users/:id/resources
With the resource as resource input in JSON:
{
uri : "http://subscriptions.play.org/foo",
name : "subscription"
}
Returns
HTTP 200 - OK
DELETE /users/:id/resources
Query Parameters
- uri: The resource uri
- name: The resource name
Returns
HTTP 204 - No content
The user object contains a list of groups he belongs to. Groups are following the resource notation. For now, API clients must use the same approach in the group endpoint than in the resource one (the only thing which is different is the resource name which is fixed to 'group').
GET /users/:id/groups
Returns a group list as JSON resource array:
HTTP 200 - OK
[
{
name: "group",
uri: "http://groups.play.org/foo
},
{
name: "group",
uri: "http://groups.play.org/bar
}
]
POST /users/:id/groups
With the group as resource input in JSON:
{
uri : "http://groups.play.org/foo",
}
Returns
HTTP 200 - OK
DELETE /users/:id/groups
Query Parameters
- uri: The group uri
Returns
HTTP 204 - No content