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 CodeMeaning
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.


Example of implementation

available here

GET /v2/endpoints
Return all the endpoints


GET /v2/endpoints/:id
Get an endpoint


POST /v2/endpoints
Create an endpoint


PATCH /v2/endpoints/:id
Update an endpoint

PUT /v2/endpoints/:id
Update an endpoint


DELETE /v2/endpoints/:id
Destroy an endpoint