TL,DR
In order to synchronize all users between the intranet and the local storage system user for authentification (like LDAP) set on a campus, each campus must set a webservice which will be called by the intranet on a user creation / update / close / unclose. A short implementation is available here.
Endpoints
The following endpoints will be called on actions on users, depending on his campus, and are:
Close
Called when a user is closed.
POST /users/%user/close
Parameters:
{
"id":5696,
"user_id":16814,
"closer_id":109,
"reason":"La raison du close",
"state":"close",
"created_at":"2016-01-23T14:59:22.789Z",
"updated_at":"2016-01-23T14:59:22.789Z",
"key"=>"a_secret_for_your_webservice"
}
Unclose
Called when a user is unclosed.
POST /users/%user/unclose
Parameters:
{
"key"=>"a_secret_for_your_webservice"
}
Update
Called when a user is updated.
POST /users/%user/update
Parameters:
# All the user fields. If the password is changed, the new password is displayed, uncrypted.
{
"uid":"andre",
"login":"andre",
"key":"a_secret_for_your_webservice",
"id":74,
"email":"andre@staff.42.fr",
"password":"the_new_password",
"created_at":"2016-01-20T00:32:50.226Z",
"updated_at":"2016-09-16T23:36:59.971Z",
"image_url":"/uploads/users/andre.jpg",
"first_name":"Andre",
"last_name":"AUBIN",
"phone":null,
"pool_year":null,
"pool_month":null,
"kind":"admin",
"status":null,
"campus":[
{
"id":1,
"name":"Paris",
"created_at":"2015-05-19T10:53:31.459Z",
"updated_at":"2016-09-22T09:11:25.476Z",
"time_zone":"Europe/Paris",
"language_id":1,
"slug":"paris",
"main_email":"general@staff.42.fr",
"endpoint_id":1,
"vogsphere_id":1
}
],
"primary_campus":{
"id":1,
"name":"Paris",
"created_at":"2015-05-19T10:53:31.459Z",
"updated_at":"2016-09-22T09:11:25.476Z",
"time_zone":"Europe/Paris",
"language_id":1,
"slug":"paris",
"main_email":"general@staff.42.fr",
"endpoint_id":1,
"vogsphere_id":1
},
"meta":{
"additional":"informations",
"can_be":"set here"
}
}
Create
Called when a user is created.
POST /users/new
Parameters:
# All the fields of the new user.
{
"uid":"andre",
"login":"andre",
"key":"a_secret_for_your_webservice",
"id":74,
"email":"andre@staff.42.fr",
"password":"the_new_password",
"created_at":"2016-01-20T00:32:50.226Z",
"updated_at":"2016-09-16T23:36:59.971Z",
"image_url":"/uploads/users/andre.jpg",
"first_name":"Andre",
"last_name":"AUBIN",
"phone":null,
"pool_year":null,
"pool_month":null,
"kind":"admin",
"status":null,
"campus":[
{
"id":1,
"name":"Paris",
"created_at":"2015-05-19T10:53:31.459Z",
"updated_at":"2016-09-22T09:11:25.476Z",
"time_zone":"Europe/Paris",
"language_id":1,
"slug":"paris",
"main_email":"general@staff.42.fr",
"endpoint_id":1,
"vogsphere_id":1
}
],
"primary_campus":{
"id":1,
"name":"Paris",
"created_at":"2015-05-19T10:53:31.459Z",
"updated_at":"2016-09-22T09:11:25.476Z",
"time_zone":"Europe/Paris",
"language_id":1,
"slug":"paris",
"main_email":"general@staff.42.fr",
"endpoint_id":1,
"vogsphere_id":1
},
"meta":{
"additional":"informations",
"can_be":"set here"
}
}
The meta
user field contain additional information which can be added trough the API, like, for example, a group_id
, and which will not be saved in the database. The uncrypted password is shown, but will not be saved in the database. So it’s the only time it will be available on user creation.
Error handling
The implemented webserice have to handle errors correctly, and return the good HTTP response code.
Http Code | Meaning |
---|---|
404 (Not found) | The user can’t be found |
422 (Unprocessable entity) | Parameters are unprocessable or missing |
500 (Internal server error) | Error on the webservice |
200 (Ok) (or 200, 201, 204) | Ok |
It’s optional, but we encourage you to respond 200, 201 and 204 for actions.
Security and format
Exchanges MUST be done over a SSL tunnel (e.g. https).
If the endpoint requires a secret token, it will be sent with the data under the key
key.
If datas are sent, they will always be in JSON format.
Additional data
The meta
user field contain additional information which can be added trough the API, like, for example, a group_id
, and which will not be saved in the database.