Difference between revisions of "stoney core: People Resource - REST API"
(→Person creation request message body) |
(→Links) |
||
(28 intermediate revisions by 2 users not shown) | |||
Line 5: | Line 5: | ||
Basically, we want to be able to do the following things: | Basically, we want to be able to do the following things: | ||
− | * Create a new person (POST). | + | * Create a new person ([[#Person_creation_.28POST.29|POST]]). |
− | * Retrieve multiple people in the form of a list (GET). | + | * Retrieve multiple people in the form of a list ([[#People_collection_retrieval_.28GET.29|GET]]). |
− | * Retrieve a single person (GET). | + | * Retrieve a single person ([[#Person_element_retrieval_.28GET.29|GET]]). |
− | * Update an existing person (PUT). | + | * Update an existing person ([[#Person_update_.28PUT.29|PUT]]). |
− | * Update one or more values of an existing person (PATCH). | + | * Update one or more values of an existing person ([[#Person_partly_update_.28PATCH.29|PATCH]]). |
− | * Delete a single person (DELETE). | + | * Delete a single person ([[#Person_deletion_.28DELETE.29|DELETE]]). |
To get an idea what happens behind the screens, have a look at the [[stoney core: People Resource Mapping (REST - LDAP)]] documentation located in the [[:Category:Mapping (REST - LDAP)|Mapping (REST - LDAP)]] category. | To get an idea what happens behind the screens, have a look at the [[stoney core: People Resource Mapping (REST - LDAP)]] documentation located in the [[:Category:Mapping (REST - LDAP)|Mapping (REST - LDAP)]] category. | ||
Line 16: | Line 16: | ||
= People resource methods = | = People resource methods = | ||
== Person creation (POST) == | == Person creation (POST) == | ||
− | To create a new person the client needs to send a HTTP <code>POST</code> request on the people collection resource URI <code>https://api.example.com/v1/people</code> (also see [[Application_Programming_Interface_(API)#Base_URI|Base URI]]), including the associated person | + | To create a new person the client needs to send a HTTP <code>POST</code> request on the people collection resource URI <code>https://api.example.com/v1/people</code> (also see [[Application_Programming_Interface_(API)#Base_URI|Base URI]]), including the associated person information. |
The service will generate a new person and responds with a HTTP status code <code>201</code> (Created) on success. The newly created person URI is returned within the HTTP location header, which can be used by the client to gather further information about the new person. | The service will generate a new person and responds with a HTTP status code <code>201</code> (Created) on success. The newly created person URI is returned within the HTTP location header, which can be used by the client to gather further information about the new person. | ||
Line 85: | Line 85: | ||
|no | |no | ||
|The title of a person. | |The title of a person. | ||
− | | | + | |UTF-8 {64} |
|@TODO add regex | |@TODO add regex | ||
| | | | ||
Line 174: | Line 174: | ||
|string | |string | ||
|yes | |yes | ||
− | |Time zone as an [http://en.wikipedia.org/wiki/UTC_offset | + | |Time zone as an [http://en.wikipedia.org/wiki/UTC_offset offset from UTC]. |
|Offset from UTC in the form <code>UTC±[hh]:[mm]</code> | |Offset from UTC in the form <code>UTC±[hh]:[mm]</code> | ||
| | | | ||
Line 181: | Line 181: | ||
|- | |- | ||
− | |<code> | + | |<code>belongsToCustomerId</code> |
|integer | |integer | ||
|yes | |yes | ||
Line 188: | Line 188: | ||
|@TODO add regex | |@TODO add regex | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"belongsToCustomerId": 4000002</source> |
− | |||
− | |||
− | |||
|- | |- | ||
− | + | |<code>employeeOfId</code> | |
− | + | |array | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | |<code> | + | |
− | | | + | |
|no | |no | ||
− | |The | + | |The ID(s) the person is an employee of. The UID(s) can belong to one or more [[stoney_core:_Resellers_Resource_-_REST_API|resellers]] or also to one or more [[stoney_core:_Customers_Resource_-_REST_API|customers]] |
+ | |one ore more UID as integer | ||
| | | | ||
− | |||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript"> |
+ | "employeeOfId": [ | ||
+ | 4000002, | ||
+ | 4001003, | ||
+ | 4002004 | ||
+ | ] | ||
+ | </source> | ||
|- | |- | ||
− | |<code> | + | |<code>externalId</code> |
− | | | + | |integer |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
|no | |no | ||
− | |The | + | |The ID of a reference in an external database. |
+ | |Min 0, max 1e+32 | ||
| | | | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"externalId": 987654321</source> |
|} | |} | ||
Line 547: | Line 285: | ||
|object | |object | ||
|no | |no | ||
− | |In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more | + | |In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more information. |
| | | | ||
| | | | ||
Line 555: | Line 293: | ||
|} | |} | ||
− | == | + | == People retrieval (GET) == |
− | === | + | === People collection retrieval (GET) === |
To retrieve existing people, the client needs to send a HTTP <code>GET</code> request on the person's collection resource URI <code>https://api.example.com/v1/people</code>. | To retrieve existing people, the client needs to send a HTTP <code>GET</code> request on the person's collection resource URI <code>https://api.example.com/v1/people</code>. | ||
The service responds with a HTTP status code 200 (OK) on success and returns the various people. | The service responds with a HTTP status code 200 (OK) on success and returns the various people. | ||
Line 563: | Line 301: | ||
==== Sort ==== | ==== Sort ==== | ||
− | If you don't add a sort attribute, the collection will be sorted by '''id''' (ascending). If you would like a sorted collection answer, the query parameter sort must be added with the object's sort attribute(s) as the value: <code>https://api.example.com/v1/people?sort= | + | If you don't add a sort attribute, the collection will be sorted by '''id''' (ascending). If you would like a sorted collection answer, the query parameter sort must be added with the object's sort attribute(s) as the value: <code>https://api.example.com/v1/people?sort=surname,isActive</code>. For further information on filtering, sorting and searching, visit [[stoney_core:_REST_API#Filtering.2C_sorting_and_searching | stoney core: REST API]]. |
==== Search (fulltext) ==== | ==== Search (fulltext) ==== | ||
Line 569: | Line 307: | ||
==== Search (with filter) ==== | ==== Search (with filter) ==== | ||
− | To form a specific search, append the url query attribute(s) name (for example ''' | + | To form a specific search, append the url query attribute(s) name (for example '''surname''') with the desired search text: <code>https://api.example.com/v1/people?surname=example</code>. You're allowed to search for all attributes that are returned in the [[#Person_element_retrieval_response_message_body | Person element retrieval response message body]]. |
− | ==== | + | ==== People collection retrieval request message ==== |
{| class="wikitable sortable" style="width: 100%;" | {| class="wikitable sortable" style="width: 100%;" | ||
|- | |- | ||
Line 607: | Line 345: | ||
|} | |} | ||
− | ==== | + | ==== People collection retrieval response message ==== |
{| class="wikitable sortable" style="width: 100%;" | {| class="wikitable sortable" style="width: 100%;" | ||
|- | |- | ||
Line 637: | Line 375: | ||
|- | |- | ||
− | | [[# | + | | [[#people_collection_retrieval_response_object|Response body]] |
| JSON object | | JSON object | ||
| <source lang="javascript">{ ... }</source> | | <source lang="javascript">{ ... }</source> | ||
Line 643: | Line 381: | ||
|} | |} | ||
− | ====== | + | ====== People collection retrieval response message body ====== |
− | {| class="wikitable sortable" style="width: 100%;" id=" | + | {| class="wikitable sortable" style="width: 100%;" id="people_collection_retrieval_response_object" |
|- | |- | ||
− | |+ align="top" style="text-align:left;"| | + | |+ align="top" style="text-align:left;"|People Collection Retrieval Response Object |
! Parameter name | ! Parameter name | ||
! Data type | ! Data type | ||
Line 670: | Line 408: | ||
"id": 5000000, | "id": 5000000, | ||
"location": "https://api.example.com/v1/people/5000000", | "location": "https://api.example.com/v1/people/5000000", | ||
− | " | + | "title": "CEO", |
"isActive": true, | "isActive": true, | ||
− | " | + | "givenName": "Name", |
− | " | + | "surname", "Surname", |
− | " | + | "mail", "user@example.com", |
− | " | + | "preferredLanguage": "de-CH", |
− | " | + | "belongsToResellerId": 4000000, |
− | " | + | "belongsToCustomerId": 4000001, |
+ | "employeeOfId": [ | ||
+ | 4000002, | ||
+ | 4001003, | ||
+ | 4002004 | ||
+ | ] | ||
}, | }, | ||
{ | { | ||
Line 689: | Line 432: | ||
|object | |object | ||
|no | |no | ||
− | |In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more | + | |In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more information. |
| | | | ||
| | | | ||
Line 730: | Line 473: | ||
| | | | ||
|<source lang="javascript">"location": "https://api.example.com/v1/people/5000000"</source> | |<source lang="javascript">"location": "https://api.example.com/v1/people/5000000"</source> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
Line 752: | Line 485: | ||
|- | |- | ||
− | |<code> | + | |<code>givenName</code> |
|string | |string | ||
|yes | |yes | ||
− | |The | + | |The given name (first name or forename) of the address holder. |
+ | |UTF-8 {64} | ||
+ | |@TODO: Add regex | ||
| | | | ||
− | + | |<source lang="javascript">"givenName": "Name"</source> | |
− | + | ||
− | |<source lang="javascript">" | + | |
|- | |- | ||
− | |<code> | + | |<code>surname</code> |
|string | |string | ||
|yes | |yes | ||
− | | | + | |The surname (last name or family name) of the address holder. |
− | | | + | |UTF-8 {64} |
|@TODO: Add regex | |@TODO: Add regex | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"surname": "Surname"</source> |
|- | |- | ||
− | |<code> | + | |<code>mail</code> |
|string | |string | ||
|yes | |yes | ||
− | | | + | |Email address |
| | | | ||
|@TODO: Add regex | |@TODO: Add regex | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"mail": "user@example.com"</source> |
|- | |- | ||
− | |<code> | + | |<code>preferredLanguage</code> |
|string | |string | ||
|yes | |yes | ||
+ | |Language tag | ||
+ | |<nowiki>[</nowiki>[http://www.loc.gov/standards/iso639-2/php/code_list.php ISO 639-1 Code]<nowiki>]</nowiki>-<nowiki>[</nowiki>[http://www.iso.org/iso/english_country_names_and_code_elements ISO 3166-1-alpha-2 code]<nowiki>]</nowiki> | ||
| | | | ||
| | | | ||
− | + | |<source lang="javascript">"preferredLanguage": "de-CH"</source> | |
− | + | ||
− | |<source lang="javascript">" | + | |
|- | |- | ||
− | |<code> | + | |<code>belongsToResellerId</code> |
|integer | |integer | ||
|yes | |yes | ||
− | |The reseller identification number the person | + | |The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] identification number the person belongs to. |
| | | | ||
|@TODO add regex | |@TODO add regex | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"belongsToResellerId": 4000000</source> |
|- | |- | ||
− | |<code> | + | |<code>belongsToCustomerId</code> |
|integer | |integer | ||
|yes | |yes | ||
− | |The customer identification number the person | + | |The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] identification number the person belongs to |
| | | | ||
|@TODO add regex | |@TODO add regex | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"belongsToCustomerId": 4000002</source> |
+ | |||
+ | |- | ||
+ | |<code>employeeOfId</code> | ||
+ | |array | ||
+ | |no | ||
+ | |The ID(s) the person is an employee of. The UID(s) can belong to one or more [[stoney_core:_Resellers_Resource_-_REST_API|resellers]] or also to one or more [[stoney_core:_Customers_Resource_-_REST_API|customers]] | ||
+ | |one ore more UID as integer | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript"> | ||
+ | "employeeOfId": [ | ||
+ | 4000002, | ||
+ | 4001003, | ||
+ | 4002004 | ||
+ | ] | ||
+ | </source> | ||
|} | |} | ||
=== Person element retrieval (GET) === | === Person element retrieval (GET) === | ||
− | To retrieve an existing person and fetch the | + | To retrieve an existing person and fetch the information associated with it, the client needs to send a HTTP <code>GET</code> request on the person's element resource URI (such as <code>https://api.example.com/v1/people/5000001</code>. |
− | The service responds with a HTTP status code 200 (OK) on success and returns the associated person | + | The service responds with a HTTP status code 200 (OK) on success and returns the associated person information. |
==== Person element retrieval request message ==== | ==== Person element retrieval request message ==== | ||
Line 907: | Line 656: | ||
|- | |- | ||
− | |<code> | + | |<code>gender</code> |
− | | | + | |string |
|yes | |yes | ||
− | |<code> | + | |The gender of the address holder |
− | + | |Either <code>f</code> for female, <code>m</code> for male or <code>n</code> for neutral. | |
| | | | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"gender": "f"</source> |
+ | |||
+ | |- | ||
+ | |<code>title</code> | ||
+ | |string | ||
+ | |no | ||
+ | |The title of a person. | ||
+ | |UTF-8 {64} | ||
+ | |@TODO add regex | ||
+ | | | ||
+ | |<source lang="javascript">"title": "CEO"</source> | ||
|- | |- | ||
Line 927: | Line 686: | ||
|- | |- | ||
− | |<code> | + | |<code>givenName</code> |
|string | |string | ||
|yes | |yes | ||
− | |The | + | |The given name (first name or forename) of the address holder. |
− | | | + | |UTF-8 {64} |
+ | |@TODO: Add regex | ||
| | | | ||
− | + | |<source lang="javascript">"givenName": "Name"</source> | |
− | |<source lang="javascript">" | + | |
|- | |- | ||
− | |<code> | + | |<code>surname</code> |
|string | |string | ||
|yes | |yes | ||
− | | | + | |The surname (last name or family name) of the address holder. |
− | | | + | |UTF-8 {64} |
|@TODO: Add regex | |@TODO: Add regex | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"surname": "Surname"</source> |
|- | |- | ||
− | |<code> | + | |<code>preferredLanguage</code> |
|string | |string | ||
|yes | |yes | ||
+ | |Language tag | ||
+ | |<nowiki>[</nowiki>[http://www.loc.gov/standards/iso639-2/php/code_list.php ISO 639-1 Code]<nowiki>]</nowiki>-<nowiki>[</nowiki>[http://www.iso.org/iso/english_country_names_and_code_elements ISO 3166-1-alpha-2 code]<nowiki>]</nowiki> | ||
| | | | ||
| | | | ||
− | + | |<source lang="javascript">"preferredLanguage": "de-CH"</source> | |
− | + | ||
− | |<source lang="javascript">" | + | |
|- | |- | ||
− | |<code> | + | |<code>mail</code> |
|string | |string | ||
|yes | |yes | ||
− | | | + | |Email address |
| | | | ||
|@TODO: Add regex | |@TODO: Add regex | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"mail": "user@example.com"</source> |
|- | |- | ||
− | + | |<code>telephoneNumber</code> | |
− | | | + | |string |
|yes | |yes | ||
− | | | + | |Telephone number |
+ | |Phone number according to [http://en.wikipedia.org/wiki/E.164 E.164] (international dialling code, trunk code, area code, subscriber line) | ||
| | | | ||
| | | | ||
− | + | |<source lang="javascript">"telephoneNumber": "+41 11 222 33 44"</source> | |
− | |<source lang="javascript"> | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | </source> | + | |
|- | |- | ||
− | + | |<code>mobileTelephoneNumber</code> | |
− | | | + | |string |
− | | | + | |yes |
− | | | + | |Mobile telephone |
+ | |Phone number according to [http://en.wikipedia.org/wiki/E.164 E.164] (international dialling code, trunk code, area code, subscriber line). | ||
| | | | ||
| | | | ||
− | + | |<source lang="javascript">"mobileTelephoneNumber": "+41 11 222 33 44"</source> | |
− | |<source lang="javascript"> | + | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | </source> | + | |
|- | |- | ||
− | |<code> | + | |<code>timeZoneOffset</code> |
|string | |string | ||
|yes | |yes | ||
− | | | + | |Time zone as an [http://en.wikipedia.org/wiki/UTC_offset offset from UTC]. |
− | | | + | |Offset from UTC in the form <code>UTC±[hh]:[mm]</code> |
| | | | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"timeZoneOffset": "UTC+01:00"</source> |
|- | |- | ||
− | |<code> | + | |<code>belongsToResellerId</code> |
+ | |integer | ||
+ | |yes | ||
+ | |The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] identification number the person belongs to. | ||
+ | | | ||
+ | |@TODO add regex | ||
+ | | | ||
+ | |<source lang="javascript">"belongsToResellerId": 4000000</source> | ||
+ | |||
+ | |- | ||
+ | |<code>resellers</code> | ||
|string | |string | ||
|yes | |yes | ||
− | |The location URI | + | |The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] location URI the person belongs to. |
− | |@TODO add link to URI RFC | + | |A valid [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] location element URI |
+ | |@TODO add link to URI RFC | ||
| | | | ||
+ | |<source lang="javascript">"resellers": "https://api.example.com/v1/resellers/4000000"</source> | ||
+ | |||
+ | |- | ||
+ | |<code>belongsToCustomerId</code> | ||
+ | |integer | ||
+ | |yes | ||
+ | |The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] UID the person belongs to | ||
| | | | ||
− | |<source lang="javascript">" | + | |@TODO add regex |
+ | | | ||
+ | |<source lang="javascript">"belongsToCustomerId": 4000002</source> | ||
|- | |- | ||
− | |<code> | + | |<code>customers</code> |
|string | |string | ||
|yes | |yes | ||
− | |The location URI | + | |The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] location URI the person belongs to. |
− | |@TODO add link to URI RFC | + | |A valid [[stoney_core:_Customers_Resource_-_REST_API|customer's]] location element URI |
+ | |@TODO add link to URI RFC | ||
+ | | | ||
+ | |<source lang="javascript">"customers": "https://api.example.com/v1/customers/4000002"</source> | ||
+ | |||
+ | |- | ||
+ | |<code>employeeOfId</code> | ||
+ | |array | ||
+ | |no | ||
+ | |The ID(s) the person is an employee of. The UID(s) can belong to one or more [[stoney_core:_Resellers_Resource_-_REST_API|resellers]] or also to one or more [[stoney_core:_Customers_Resource_-_REST_API|customers]] | ||
+ | |one ore more UID as integer | ||
+ | | | ||
+ | | | ||
+ | |<source lang="javascript"> | ||
+ | "employeeOfId": [ | ||
+ | 4000002, | ||
+ | 4001003, | ||
+ | 4002004 | ||
+ | ] | ||
+ | </source> | ||
+ | |||
+ | |- | ||
+ | |<code>externalId</code> | ||
+ | |integer | ||
+ | |no | ||
+ | |The ID of a reference in an external database. | ||
+ | |Min 0, max 1e+32 | ||
| | | | ||
| | | | ||
− | |<source lang="javascript">" | + | |<source lang="javascript">"externalId": 987654321</source> |
|- | |- | ||
Line 1,054: | Line 826: | ||
|object | |object | ||
|no | |no | ||
− | |In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more | + | |In case of a failure, an error object with the appropriate error messages will be returned. Refer to the [[stoney_core:_REST_API#Error_codes_and_responses|Error codes and response chapter]] for more information. |
| | | | ||
| | | | ||
Line 1,141: | Line 913: | ||
==== Person update response message body ==== | ==== Person update response message body ==== | ||
− | On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further | + | On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further information about the failure. |
== Person partly update (PATCH) == | == Person partly update (PATCH) == | ||
Line 1,189: | Line 961: | ||
==== Person partly update request message body ==== | ==== Person partly update request message body ==== | ||
The JSON message body consists out of one or more fields from the [[#person_object|Person object]]. | The JSON message body consists out of one or more fields from the [[#person_object|Person object]]. | ||
− | |||
=== Person partly update response message === | === Person partly update response message === | ||
Line 1,220: | Line 991: | ||
==== Person partly update response message body ==== | ==== Person partly update response message body ==== | ||
− | On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further | + | On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further information about the failure. |
== Person deletion (DELETE) == | == Person deletion (DELETE) == | ||
Line 1,290: | Line 1,061: | ||
==== Person deletion response message body ==== | ==== Person deletion response message body ==== | ||
− | On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further | + | On success (<code>200</code>) an empty response message body will be returned, otherwise an [[stoney_core:_REST_API#Error_codes_and_responses|error object]] will provide further information about the failure. |
== People search == | == People search == | ||
Line 1,297: | Line 1,068: | ||
= Links = | = Links = | ||
* [[stoney core: REST API]] | * [[stoney core: REST API]] | ||
+ | |||
+ | Hello world! | ||
[[Category:REST API]][[Category:stoney core]] | [[Category:REST API]][[Category:stoney core]] |
Latest revision as of 10:55, 5 January 2015
Also visit stoney core: People Resource Mapping (REST - LDAP).
Contents
Overview
The REST API describes the (Representational State Transfer Application Programming Interface) of the people resource to be used by stoney core, stoney conductor and other Self-Service Modules or third party applications.
Basically, we want to be able to do the following things:
- Create a new person (POST).
- Retrieve multiple people in the form of a list (GET).
- Retrieve a single person (GET).
- Update an existing person (PUT).
- Update one or more values of an existing person (PATCH).
- Delete a single person (DELETE).
To get an idea what happens behind the screens, have a look at the stoney core: People Resource Mapping (REST - LDAP) documentation located in the Mapping (REST - LDAP) category.
People resource methods
Person creation (POST)
To create a new person the client needs to send a HTTP POST
request on the people collection resource URI https://api.example.com/v1/people
(also see Base URI), including the associated person information.
The service will generate a new person and responds with a HTTP status code 201
(Created) on success. The newly created person URI is returned within the HTTP location header, which can be used by the client to gather further information about the new person.
Person creation request message
HTTP request part | Content | Example |
---|---|---|
Request lines | POST <Request-URI> HTTP 1.1 HOST: <Host> |
POST /v1/people/ HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> Content-Type: <Type>/<Subtype>; charset=<Charset> |
Accept: application/json Accept-Charset: UTF-8 Content-Type: application/json; charset=UTF-8 |
Request body | JSON object | { ... } |
Person creation request message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
gender
|
string | yes | The gender of the address holder | Either f for female, m for male or n for neutral.
|
"gender": "f" | ||
title
|
string | no | The title of a person. | UTF-8 {64} | @TODO add regex | "title": "CEO" | |
isActive
|
boolean | no | Is the entry active | true or false
|
true
|
"isActive": true | |
givenName
|
string | yes | The given name (first name or forename) of the address holder. | UTF-8 {64} | @TODO: Add regex | "givenName": "Name" | |
surname
|
string | yes | The surname (last name or family name) of the address holder. | UTF-8 {64} | @TODO: Add regex | "surname": "Surname" | |
preferredLanguage
|
string | yes | Language tag | [ISO 639-1 Code]-[ISO 3166-1-alpha-2 code] | "preferredLanguage": "de-CH" | ||
password
|
string | yes | Password | min 8 chars, max 255 chars | "password": "dontstealme!" | ||
mail
|
string | yes | Email address | @TODO: Add regex | "mail": "user@example.com" | ||
telephoneNumber
|
string | yes | Telephone number | Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line) | "telephoneNumber": "+41 11 222 33 44" | ||
mobileTelephoneNumber
|
string | yes | Mobile telephone | Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line). | "mobileTelephoneNumber": "+41 11 222 33 44" | ||
timeZoneOffset
|
string | yes | Time zone as an offset from UTC. | Offset from UTC in the form UTC±[hh]:[mm]
|
"timeZoneOffset": "UTC+01:00" | ||
belongsToCustomerId
|
integer | yes | the customer UID the person belongs to | @TODO add regex | "belongsToCustomerId": 4000002 | ||
employeeOfId
|
array | no | The ID(s) the person is an employee of. The UID(s) can belong to one or more resellers or also to one or more customers | one ore more UID as integer | "employeeOfId": [ 4000002, 4001003, 4002004 ] | ||
externalId
|
integer | no | The ID of a reference in an external database. | Min 0, max 1e+32 | "externalId": 987654321 |
Person creation response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 201 Created |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> Location: <Location-URI> |
Content-Type: Content-Type: application/json; charset=UTF-8 Location: https://api.example.com/v1/people/5000001 |
Response body | JSON object | { ... } |
Person creation response message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
id
|
integer | yes | The identification number of the newly created person resource. | @TODO add regex | "id": 5000001 | ||
location
|
string | yes | The location URI of the newly created person resource, corresponds with the HTTP location header. | @TODO add link to URI RFC | "location": "https://api.example.com/v1/people/5000001" | ||
error
|
object | no | In case of a failure, an error object with the appropriate error messages will be returned. Refer to the Error codes and response chapter for more information. | "error": { /* ... */ } |
People retrieval (GET)
People collection retrieval (GET)
To retrieve existing people, the client needs to send a HTTP GET
request on the person's collection resource URI https://api.example.com/v1/people
.
The service responds with a HTTP status code 200 (OK) on success and returns the various people.
Note that the service will only return a limited amount of objects at once and provides links for retrieving further objects. Refer to the Pagination chapter for more information.
Sort
If you don't add a sort attribute, the collection will be sorted by id (ascending). If you would like a sorted collection answer, the query parameter sort must be added with the object's sort attribute(s) as the value: https://api.example.com/v1/people?sort=surname,isActive
. For further information on filtering, sorting and searching, visit stoney core: REST API.
Search (fulltext)
To form a fulltext search (people only), append the url query parameter q with the desired search text: https://api.example.com/v1/people?q=example
. The document stoney core: Search Resource - REST API describes the search in detail.
Search (with filter)
To form a specific search, append the url query attribute(s) name (for example surname) with the desired search text: https://api.example.com/v1/people?surname=example
. You're allowed to search for all attributes that are returned in the Person element retrieval response message body.
People collection retrieval request message
HTTP request part | Content | Example |
---|---|---|
Request lines | GET <Request-URI> HTTP 1.1 HOST: <Host> |
GET /v1/people/ HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> |
Accept: application/json Accept-Charset: UTF-8 |
Request body | <Empty> |
People collection retrieval response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> Location: <Location-URI> Link: X-Total-Count: |
Content-Type: Content-Type: application/json; charset=UTF-8 Link: <https://api.example.com/v1/people?page=1&per_page=30>; rel="first", <https://api.example.com/v1/people?page=2&per_page=30>; rel="prev", <https://api.example.com/v1/people?page=4&per_page=30>; rel="next", <https://api.example.com/v1/people?page=10&per_page=30>; rel="last" X-Total-Count: 295 |
Response body | JSON object | { ... } |
People collection retrieval response message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example
|
---|---|---|---|---|---|---|---|
array | no | An array with one or more person collection objects | [ { "id": 5000000, "location": "https://api.example.com/v1/people/5000000", "title": "CEO", "isActive": true, "givenName": "Name", "surname", "Surname", "mail", "user@example.com", "preferredLanguage": "de-CH", "belongsToResellerId": 4000000, "belongsToCustomerId": 4000001, "employeeOfId": [ 4000002, 4001003, 4002004 ] }, { /* ... */ } ] | ||||
error
|
object | no | In case of a failure, an error object with the appropriate error messages will be returned. Refer to the Error codes and response chapter for more information. | error { /* ... */ } |
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
id
|
integer | yes | The identification number of the person. | @TODO add regex | "id": 5000000 | ||
location
|
string | yes | The location URI of the person resource. | @TODO add link to URI RFC | "location": "https://api.example.com/v1/people/5000000" | ||
isActive
|
boolean | yes | true or false
|
true
|
"isActive": true | ||
givenName
|
string | yes | The given name (first name or forename) of the address holder. | UTF-8 {64} | @TODO: Add regex | "givenName": "Name" | |
surname
|
string | yes | The surname (last name or family name) of the address holder. | UTF-8 {64} | @TODO: Add regex | "surname": "Surname" | |
mail
|
string | yes | Email address | @TODO: Add regex | "mail": "user@example.com" | ||
preferredLanguage
|
string | yes | Language tag | [ISO 639-1 Code]-[ISO 3166-1-alpha-2 code] | "preferredLanguage": "de-CH" | ||
belongsToResellerId
|
integer | yes | The reseller's identification number the person belongs to. | @TODO add regex | "belongsToResellerId": 4000000 | ||
belongsToCustomerId
|
integer | yes | The customer's identification number the person belongs to | @TODO add regex | "belongsToCustomerId": 4000002 | ||
employeeOfId
|
array | no | The ID(s) the person is an employee of. The UID(s) can belong to one or more resellers or also to one or more customers | one ore more UID as integer | "employeeOfId": [ 4000002, 4001003, 4002004 ] |
Person element retrieval (GET)
To retrieve an existing person and fetch the information associated with it, the client needs to send a HTTP GET
request on the person's element resource URI (such as https://api.example.com/v1/people/5000001
.
The service responds with a HTTP status code 200 (OK) on success and returns the associated person information.
Person element retrieval request message
HTTP request part | Content | Example |
---|---|---|
Request lines | GET <Request-URI> HTTP 1.1 HOST: <Host> |
GET /v1/people/5000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> |
Accept: application/json Accept-Charset: UTF-8 |
Request body | <Empty> |
Person element retrieval response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> Location: <Location-URI> |
Content-Type: Content-Type: application/json; charset=UTF-8 Location: https://api.example.com/v1/people/5000001 |
Response body | JSON object | { ... } |
Person element retrieval response message body
Parameter name | Data type | Mandatory | Description | Valid content | PCRE | Default value | Example |
---|---|---|---|---|---|---|---|
id
|
integer | yes | The identification number of the person. | @TODO add regex | "id": 5000001 | ||
gender
|
string | yes | The gender of the address holder | Either f for female, m for male or n for neutral.
|
"gender": "f" | ||
title
|
string | no | The title of a person. | UTF-8 {64} | @TODO add regex | "title": "CEO" | |
isActive
|
boolean | yes | true or false
|
true
|
"isActive": true | ||
givenName
|
string | yes | The given name (first name or forename) of the address holder. | UTF-8 {64} | @TODO: Add regex | "givenName": "Name" | |
surname
|
string | yes | The surname (last name or family name) of the address holder. | UTF-8 {64} | @TODO: Add regex | "surname": "Surname" | |
preferredLanguage
|
string | yes | Language tag | [ISO 639-1 Code]-[ISO 3166-1-alpha-2 code] | "preferredLanguage": "de-CH"
| ||
mail
|
string | yes | Email address | @TODO: Add regex | "mail": "user@example.com" | ||
telephoneNumber
|
string | yes | Telephone number | Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line) | "telephoneNumber": "+41 11 222 33 44" | ||
mobileTelephoneNumber
|
string | yes | Mobile telephone | Phone number according to E.164 (international dialling code, trunk code, area code, subscriber line). | "mobileTelephoneNumber": "+41 11 222 33 44" | ||
timeZoneOffset
|
string | yes | Time zone as an offset from UTC. | Offset from UTC in the form UTC±[hh]:[mm]
|
"timeZoneOffset": "UTC+01:00" | ||
belongsToResellerId
|
integer | yes | The reseller's identification number the person belongs to. | @TODO add regex | "belongsToResellerId": 4000000 | ||
resellers
|
string | yes | The reseller's location URI the person belongs to. | A valid reseller's location element URI | @TODO add link to URI RFC | "resellers": "https://api.example.com/v1/resellers/4000000" | |
belongsToCustomerId
|
integer | yes | The customer's UID the person belongs to | @TODO add regex | "belongsToCustomerId": 4000002 | ||
customers
|
string | yes | The customer's location URI the person belongs to. | A valid customer's location element URI | @TODO add link to URI RFC | "customers": "https://api.example.com/v1/customers/4000002" | |
employeeOfId
|
array | no | The ID(s) the person is an employee of. The UID(s) can belong to one or more resellers or also to one or more customers | one ore more UID as integer | "employeeOfId": [ 4000002, 4001003, 4002004 ] | ||
externalId
|
integer | no | The ID of a reference in an external database. | Min 0, max 1e+32 | "externalId": 987654321 | ||
error
|
object | no | In case of a failure, an error object with the appropriate error messages will be returned. Refer to the Error codes and response chapter for more information. | "error": { /* ... */ } |
Person update (PUT)
To updates an existing person, the client needs to send a HTTP PUT
request on the person's element resource URI (such as, https://api.example.com/v1/people/5000001
).
The service responds with a HTTP status code 200 (OK) on success and returns an empty body.
The PUT
method requires one to sent the complete record, thus the work-flow is normally as follows:
- A GET request on the Person element URI will be made to fetch the whole document.
- Update the fields which content has changed
- Send a
PUT
request with all the person data
Person update request message
HTTP request part | Content | Example |
---|---|---|
Request lines | PUT <Request-URI> HTTP 1.1 HOST: <Host> |
PUT /v1/people/5000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> Content-Type: <Type>/<Subtype>; charset=<Charset> |
Accept: application/json Accept-Charset: UTF-8 Content-Type: application/json; charset=UTF-8 |
Request body | JSON object | { ... } |
Person update request message body
See Person object.
Person update response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> |
Content-Type: Content-Type: application/json; charset=UTF-8 |
Response body | JSON object | { ... } |
Person update response message body
On success (200
) an empty response message body will be returned, otherwise an error object will provide further information about the failure.
Person partly update (PATCH)
To update fields of an existing person, the client needs to send a HTTP PATCH
request on the person's element resource URI (such as, https://api.example.com/v1/people/5000001
).
The service responds with a HTTP status code 200 (OK) on success and returns an empty body.
In contrast to the PUT
method, only the changed fields are to be included in the request.
Person partly update request message
HTTP request part | Content | Example |
---|---|---|
Request lines | PATCH <Request-URI> HTTP 1.1 HOST: <Host> |
PATCH /v1/people/5000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> Content-Type: <Type>/<Subtype>; charset=<Charset> |
Accept: application/json Accept-Charset: UTF-8 Content-Type: application/json; charset=UTF-8 |
Request body | JSON object | { ... } |
Person partly update request message body
The JSON message body consists out of one or more fields from the Person object.
Person partly update response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> |
Content-Type: Content-Type: application/json; charset=UTF-8 |
Response body | JSON object | { ... } |
Person partly update response message body
On success (200
) an empty response message body will be returned, otherwise an error object will provide further information about the failure.
Person deletion (DELETE)
To delete an existing person, the client needs to send a HTTP DELETE
request, with an empty request body on the person's element resource URI (such as, https://api.example.com/v1/people/5000001
). The service responds with a HTTP status code 200
(OK) on success and returns an empty body.
Person deletion request message
HTTP request part | Content | Example |
---|---|---|
Request lines | DELETE <Request-URI> HTTP 1.1 HOST: <Host> |
DELETE /v1/people/5000001 HTTP 1.1 HOST: api.example.com |
Request headers | Accept: <Type>/<Subtype> Accept-Charset: <Charset> |
Accept: application/json Accept-Charset: UTF-8 |
Request body | <Empty> |
Person deletion response message
HTTP response part | Content | Example |
---|---|---|
Status Line | HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message> |
HTTP/1.1 200 OK |
Response headers | Content-Type: <Type>/<Subtype>; charset=<Charset> |
Content-Type: Content-Type: application/json; charset=UTF-8 |
Response body | JSON object | { ... } |
Person deletion response message body
On success (200
) an empty response message body will be returned, otherwise an error object will provide further information about the failure.
People search
The people search is a sub section of the stoney core: Search Resource - REST API and is described there in more detail.
Links
Hello world!