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.
|no
|The title of a person.
|UTF-8 {64}
|@TODO add regex
|
|-
|<code>belongsToCustomerIDbelongsToCustomerId</code>
|integer
|yes
|@TODO add regex
|
|<source lang="javascript">"belongsToCustomerIDbelongsToCustomerId": 4000002</source>
|-
|<code>employeeOfIDemployeeOfId</code>
|array
|no
|
|<source lang="javascript">
"employeeOfIDemployeeOfId": [
4000002,
4001003,
|-
|<code>externalIDexternalId</code>
|integer
|no
|
|
|<source lang="javascript">"externalIDexternalId": 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.
|
|
==== Search (with filter) ====
To form a specific search, append the url query attribute(s) name (for example '''personNamesurname''') with the desired search text: <code>https://api.example.com/v1/people?personNamesurname=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]].
==== Person People collection retrieval request message ====
{| class="wikitable sortable" style="width: 100%;"
|-
|}
==== Person People collection retrieval response message ====
{| class="wikitable sortable" style="width: 100%;"
|-
|-
| [[#person_collection_retrieval_response_objectpeople_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
====== Person People collection retrieval response message body ======{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_objectpeople_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person People Collection Retrieval Response Object
! Parameter name
! Data type
"id": 5000000,
"location": "https://api.example.com/v1/people/5000000",
"isCompanytitle": true"CEO",
"isActive": true,
"personNamegivenName": "Person LtdName", "countryCodesurname": , "CHSurname", "postalCodemail": , "3012user@example.com", "localityNamepreferredLanguage": "Bernde-CH", "belongsToResellerIDbelongsToResellerId": 4000000, "belongsToCustomerIDbelongsToCustomerId": 4000001, "employeeOfId": [ 4000002, 4001003, 4002004 ]
},
{
|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">"location": "https://api.example.com/v1/people/5000000"</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": "CHSurname"</source>
|-
|<code>postalCodemail</code>
|string
|yes
|Email address
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCodemail": "3012user@example.com"</source>
|-
|<code>localityNamepreferredLanguage</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>belongsToResellerIDbelongsToResellerId</code>
|integer
|yes
|The [[stoney_core:_Resellers_Resource_-_REST_API|reseller 's]] identification number the person resource must belong belongs to.
|
|@TODO add regex
|
|<source lang="javascript">"idbelongsToResellerId": 4000000</source>
|-
|<code>belongsToCustomerIDbelongsToCustomerId</code>
|integer
|yes
|The [[stoney_core:_Customers_Resource_-_REST_API|customer 's]] identification number the person resource must belong belongs to.
|
|@TODO add regex
|
|<source lang="javascript">"idbelongsToCustomerId": 40000004000002</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) ===
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:00"</source> |-|<code>belongsToResellerId</apicode>|integer|yes|The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] identification number the person belongs to.example.com/v1/people/5000001/people||@TODO add regex||<source lang="javascript">"belongsToResellerId": 4000000</source>
|-
|<code>employeesresellers</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">"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">"usersexternalId": "https://api.example.com/v1/people/5000001/users"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]]
