Changes
/* Links */
Basically, we want to be able to do the following things:
* Create a new person ([[#Person_creation_.28POST.29|POST]]).* Retrieve multiple people in the form of a list ([[#People_collection_retrieval_.28GET.29|GET]]).* Retrieve a single person ([[#Person_element_retrieval_.28GET.29|GET]]).* Update an existing person ([[#Person_update_.28PUT.29|PUT]]).* Update one or more values of an existing person ([[#Person_partly_update_.28PATCH.29|PATCH]]).* 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.
= People resource methods =
== 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 informationsinformation.
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.
|object
|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 informationsinformation.
|
|
|object
|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 informationsinformation.
|
|
|
|<source lang="javascript">"preferredLanguage": "de-CH"</source>
|-
|<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>
|-
|integer
|yes
|the The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] UID identification number the person belongs to
|
|@TODO add regex
=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informationsinformation.
==== Person element retrieval request message ====
|-
|<code>isCompanygender</code>|booleanstring
|yes
|The gender of the address holder|Either <code>truef</code> if the person represents a companyfor female, <code>false</code> if it's an individual person.|<code>truem</code> for male or <code>falsen</code>for neutral.
|
|
|<source lang="javascript">"isCompanygender": true"f"</source> |-|<code>title</code>|string|no|The title of a person. |UTF-8 {64}|@TODO add regex||<source lang="javascript">"title": "CEO"</source>
|-
|-
|<code>personNamegivenName</code>
|string
|yes
|The person's display given name (first name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out forename) of the [[#billingAddress_objectaddress holder.|billingAddress object]], but can also be the name of a brand.UTF-8 {64}|@TODO: Add regex
|
|-
|<code>countryCodesurname</code>
|string
|yes
|The surname (last name or family name) of the address holder.|UTF-8 {64}
|@TODO: Add regex
|
|<source lang="javascript">"countryCodesurname": "Surname"</source>
|-
|<code>postalCodepreferredLanguage</code>
|string
|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>
|
|
|-
|<code>localityNamemail</code>
|string
|yes
|Email address
|
|@TODO: Add regex
|
|<source lang="javascript">"localityNamemail": "user@example.com"</source>
|-
|yes
|An object holding the billing address informations for the given person. Refer Telephone number|Phone number according to the [[#billingAddress_object|billingAddress object table]] for more informationshttp://en.wikipedia.org/wiki/E.164 E.164] (international dialling code, trunk code, area code, subscriber line)
|
|
|-
|
|
|-
|<code>peopletimeZoneOffset</code>
|string
|yes
|The location URI of the people belonging to this person resourceTime zone as an [http://en.wikipedia.org/wiki/UTC_offset offset from UTC].|@TODO add link to URI RFC Offset from UTC in the form <code>UTC±[hh]:[mm]</code>
|
|
|<source lang="javascript">"peopletimeZoneOffset": "httpsUTC+01://api.example.com/v1/people/5000001/people00"</source>
|-
|<code>employeesbelongsToResellerId</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
|yes
|The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] location URI of the employees belonging to this person resourcebelongs to.|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
|
|@TODO add regex||<source lang="javascript">"employeesbelongsToCustomerId": "https://api.example.com/v1/people/5000001/employees"4000002</source>
|-
|<code>userscustomers</code>
|string
|yes
|The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] location URI of the users belonging to this person resourcebelongs to.|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">"usersemployeeOfId": "https:[ 4000002, 4001003, 4002004]</source> |-|<code>externalId</apicode>|integer|no|The ID of a reference in an external database.example.com/v1/people/5000001/users|Min 0, max 1e+32|||<source lang="javascript">"externalId": 987654321</source>
|-
|object
|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 informationsinformation.
|
|
==== 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 informations information about the failure.
== Person partly update (PATCH) ==
==== Person partly update request message body ====
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 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 informations information about the failure.
== Person deletion (DELETE) ==
==== 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 informations information about the failure.
== People search ==
= Links =
* [[stoney core: REST API]]
Hello world!
[[Category:REST API]][[Category:stoney core]]
