Document and improve current Rails API to create people

[RolandStuder]

#527 is not within the the current clients budget, but their use use cases can already be achieved with the current APIs that rails provides.

However documentation for those is lacking also validations just return empty errors.

So we will do the following:

• Create documentation to use current JSON API in English, documentation should be either in https://github.com/hitobito/hitobito/blob/master/doc/development/05_rest_api.md or maybe in a new folder /doc/api
• Return validation errors, if possible in requested :locale
• will not support requests directly from browsers (because of CSRF)

We will only do the minimal version, so we just need to make it available to create roles, as seen in the first example

Important for documentation

• Note that a primary e-mail Adress must be unique. So for the intented purpose it might be easier, to just always create a person without using the Primary email-adress (:email) and to just use additional-email addresses.
• Give some indication as to where they can get group id and available roles types.
• To create a user without a role is not recommended as nobody will find that person, unless specifically looking for that entry, if you have an admin permission, or if you try to add the person somewhere else.

Open questions:

• If API consumers want to add the role and update existing user, then we also need to document the following:
  • update user with additional accounts / phone numbers...
  • create role
  • update role
  • delete role
  • (delete person is very restricted)

Examples:

** Create Person with additional Email (assumes role type and group id are known) **

$ curl -v -H 'X-User-Email: maierhofer@puzzle.ch' -H 'X-User-Token: Lzu45TpKYavceGzYssys' -H 'Content-Type: application/json' -d '{"role": { "new_person": { "email": "test2@xample.com", "first_name": "a", "last_name": "b", "additional_email_attributes": [ { "name": "privat", "translated_label": "msn", "mailings": "0", "public": "1" } ] }, "type": "Group::TopLayer::Administrator" } }' http://localhost:3000/en/groups/1/roles.json

*   Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> POST /en/groups/1/roles.json HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.47.0
> Accept: */*
> X-User-Email: maierhofer@puzzle.ch
> X-User-Token: Lzu45TpKYavceGzYssys
> Content-Type: application/json
> Content-Length: 255
>
* upload completely sent off: 255 out of 255 bytes
< HTTP/1.1 201 Created
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Location: /en/groups/1/people/494
< Content-Type: application/json; charset=utf-8
< Vary: Accept-Encoding
< Set-Cookie: locale=en; path=/; expires=Wed, 17 Apr 2019 07:03:58 -0000
< X-Request-Id: 66eb1161-6c42-49d1-b993-218bbcb8fa83
< X-Runtime: 0.136539
< Connection: close
< Server: thin 1.5.1 codename Straight Razor
<
* Closing connection 0
{"id":491,"person_id":494,"group_id":1,"label":null,"created_at":"2018-04-17T09:03:58.435+02:00","updated_at":"2018-04-17T09:03:58.435+02:00","deleted_at":null} {feature/527-api} hitobito$
"}" } ] } }}'

** Create Person failed (email already taken) **

$ curl -v -H 'X-User-Email: maierhofer@puzzle.ch' -H 'X-User-Token: Lzu45TpKYavceGzYssys' -H 'Content-Type: application/json' -d '{"role": { "new_person": { "email": "test2@xample.com", "first_name": "a", "last_name": "b", "additional_email_attributes": [ { "name": "privat", "translated_label": "msn", "mailings": "0", "public": "1"  }  ]  }, "type": "Group::TopLayer::Administrator"  } }' http://localhost:3000/en/groups/1/roles.json

* Trying 127.0.0.1...
* Connected to localhost (127.0.0.1) port 3000 (#0)
> POST /en/groups/1/roles.json HTTP/1.1
> Host: localhost:3000
> User-Agent: curl/7.47.0
> Accept: */*
> X-User-Email: maierhofer@puzzle.ch
> X-User-Token: Lzu45TpKYavceGzYssys
> Content-Type: application/json
> Content-Length: 255
>
* upload completely sent off: 255 out of 255 bytes
< HTTP/1.1 422
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: Fri, 01 Jan 1990 00:00:00 GMT
< Content-Type: application/json; charset=utf-8
< Vary: Accept-Encoding
< Set-Cookie: locale=en; path=/; expires=Wed, 17 Apr 2019 07:05:30 -0000
< X-Request-Id: 482e88c9-775d-4b18-9e69-f0c71f573ba7
< X-Runtime: 0.119221
< Connection: close
< Server: thin 1.5.1 codename Straight Razor
<
* Closing connection 0
{"errors":{}}