Changes
/* Links */
Also visit [[stoney core: People Resource Mapping (REST - LDAP)]].
= Overview =
The REST API describes the ('''Re'''presentational '''S'''tate '''T'''ransfer '''A'''pplication '''P'''rogramming '''I'''nterface) of the people resource to be used by [[:Category:stoney core|stoney core]], [[:Category:stoney conductor|stoney conductor]] and other [[:Category:Self-Service Modules|Self-Service Modules]] or third party applications.
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 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.
=== Person creation request message ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP request part
! Content
! Example
|-
| Request lines
|<pre>
POST <Request-URI> HTTP 1.1
HOST: <Host>
</pre>
|<pre>
POST /v1/people/ HTTP 1.1
HOST: api.example.com
</pre>
|-
| Request headers
| <pre>
Accept: <Type>/<Subtype>
Accept-Charset: <Charset>
Content-Type: <Type>/<Subtype>; charset=<Charset>
</pre>
| <pre>
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json; charset=UTF-8
</pre>
|-
| [[#Person_creation_request_message_body|Request body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== Person creation request message body ====
{| class="wikitable sortable" style="width: 100%;" id="person_object"
|-
|+ align="top" style="text-align:left;"|Person Object
! Parameter name
! Data type
! Mandatory
! Description
! Valid content
![http://www.pcre.org/ PCRE]
! Default value
! Example
|-
|<code>gender</code>
|string
|yes
|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">"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>
|-
|<code>isActive</code>
|boolean
|no
|Is the entry active
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>
|-
|<code>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
|<source lang="javascript">"givenName": "Name"</source>
|-
|<code>surname</code>
|string
|yes
|The surname (last name or family name) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>
|-
|<code>preferredLanguage</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>
|
|
|<source lang="javascript">"preferredLanguage": "de-CH"</source>
|-
|<code>password</code>
|string
|yes
|Password
|min 8 chars, max 255 chars
|
|
|<source lang="javascript">"password": "dontstealme!"</source>
|-
|<code>mail</code>
|string
|yes
|Email address
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": "user@example.com"</source>
|-
|<code>telephoneNumber</code>
|string
|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>
|-
|<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>
|-
|<code>timeZoneOffset</code>
|string
|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">"timeZoneOffset": "UTC+01:00"</source>
|-
|<code>belongsToCustomerId</code>
|integer
|yes
|the [[stoney_core:_Customers_Resource_-_REST_API|customer]] UID the person belongs to
|
|@TODO add regex
|
|<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>
|-
|<code>externalId</code>
|integer
|no
|The ID of a reference in an external database.
|Min 0, max 1e+32
|
|
|<source lang="javascript">"externalId": 987654321</source>
|}
=== Person creation response message ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP response part
! Content
! Example
|-
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 201 Created</pre>
|-
| Response headers
|<pre>
Content-Type: <Type>/<Subtype>; charset=<Charset>
Location: <Location-URI>
</pre>
|<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
Location: https://api.example.com/v1/people/5000001
</pre>
|-
| [[#Person_creation_response_message_body|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== Person creation response message body ====
{| class="wikitable sortable" style="width: 100%;" id="person_creation_response_object"
|-
|+ align="top" style="text-align:left;"|Person Creation Response Object
! Parameter name
! Data type
! Mandatory
! Description
! Valid content
![http://www.pcre.org/ PCRE]
! Default value
! Example
|-
|<code>id</code>
|integer
|yes
|The identification number of the newly created person resource.
|
|@TODO add regex
|
|<source lang="javascript">"id": 5000001</source>
|-
|<code>location</code>
|string
|yes
|The location URI of the newly created person resource, corresponds with the HTTP location header.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"location": "https://api.example.com/v1/people/5000001"</source>
|-
|[[stoney_core:_REST_API#Error_codes_and_responses|<code>error</code>]]
|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 information.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>
|}
== 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>.
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 [[stoney_core:_REST_API#Pagination|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: <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) ====
To form a fulltext search (people only), append the url query parameter '''q''' with the desired search text: <code>https://api.example.com/v1/people?q=example</code>. The document [[stoney_core:_Search_Resource_-_REST_API#People_Search_.28GET.29 | 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: <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%;"
|-
! HTTP request part
! Content
! Example
|-
| Request lines
|<pre>
GET <Request-URI> HTTP 1.1
HOST: <Host>
</pre>
|<pre>
GET /v1/people/ HTTP 1.1
HOST: api.example.com
</pre>
|-
| Request headers
| <pre>
Accept: <Type>/<Subtype>
Accept-Charset: <Charset>
</pre>
| <pre>
Accept: application/json
Accept-Charset: UTF-8
</pre>
|-
| Request body
| <Empty>
| <pre></pre>
|}
==== People collection retrieval response message ====
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP response part
! Content
! Example
|-
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 200 OK</pre>
|-
| Response headers
|<pre>
Content-Type: <Type>/<Subtype>; charset=<Charset>
Location: <Location-URI>
Link:
X-Total-Count:
</pre>
|<pre>
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
</pre>
|-
| [[#people_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
====== People collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="people_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|People Collection Retrieval Response Object
! Parameter name
! Data type
! Mandatory
! Description
! Valid content
! [http://www.pcre.org/ PCRE]
! Default value
! Example
|-
|
|array
|no
|An array with one or more [[#person_collection_array_element_object|person collection objects]]
|
|
|
|<source lang="javascript">
[
{
"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
]
},
{
/* ... */
}
]
</source>
|-
|[[stoney_core:_REST_API#Error_codes_and_responses|<code>error</code>]]
|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 information.
|
|
|
|<source lang="javascript">error { /* ... */ }</source>
|}
{| class="wikitable sortable" style="width: 100%;" id="person_collection_array_element_object"
|-
|+ align="top" style="text-align:left;"|Person Collection Array Element Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example
|-
|<code>id</code>
|integer
|yes
|The identification number of the person.
|
|@TODO add regex
|
|<source lang="javascript">"id": 5000000</source>
|-
|<code>location</code>
|string
|yes
|The location URI of the person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"location": "https://api.example.com/v1/people/5000000"</source>
|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>
|-
|<code>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
|<source lang="javascript">"givenName": "Name"</source>
|-
|<code>surname</code>
|string
|yes
|The surname (last name or family name) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>
|-
|<code>mail</code>
|string
|yes
|Email address
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": "user@example.com"</source>
|-
|<code>preferredLanguage</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>
|
|
|<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>
|-
|<code>belongsToCustomerId</code>
|integer
|yes
|The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] identification number the person belongs to
|
|@TODO add regex
|
|<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) ===
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 information.
==== Person element retrieval request message ====
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP request part
! Content
! Example
|-
| Request lines
|<pre>
GET <Request-URI> HTTP 1.1
HOST: <Host>
</pre>
|<pre>
GET /v1/people/5000001 HTTP 1.1
HOST: api.example.com
</pre>
|-
| Request headers
| <pre>
Accept: <Type>/<Subtype>
Accept-Charset: <Charset>
</pre>
| <pre>
Accept: application/json
Accept-Charset: UTF-8
</pre>
|-
| Request body
| <Empty>
| <pre></pre>
|}
==== Person element retrieval response message ====
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP response part
! Content
! Example
|-
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 200 OK</pre>
|-
| Response headers
|<pre>
Content-Type: <Type>/<Subtype>; charset=<Charset>
Location: <Location-URI>
</pre>
|<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
Location: https://api.example.com/v1/people/5000001
</pre>
|-
| [[#Person_element_retrieval_response_message_body|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
====== Person element retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_element_retrival_response_object"
|-
|+ align="top" style="text-align:left;"|Person Element Retrieval Response Object
! Parameter name
! Data type
! Mandatory
! Description
! Valid content
! [http://www.pcre.org/ PCRE]
! Default value
! Example
|-
|<code>id</code>
|integer
|yes
|The identification number of the person.
|
|@TODO add regex
|
|<source lang="javascript">"id": 5000001</source>
|-
|<code>gender</code>
|string
|yes
|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">"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>
|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>
|-
|<code>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
|<source lang="javascript">"givenName": "Name"</source>
|-
|<code>surname</code>
|string
|yes
|The surname (last name or family name) of the address holder.
|UTF-8 {64}
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>
|-
|<code>preferredLanguage</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>
|
|
|<source lang="javascript">"preferredLanguage": "de-CH"</source>
|-
|<code>mail</code>
|string
|yes
|Email address
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": "user@example.com"</source>
|-
|<code>telephoneNumber</code>
|string
|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>
|-
|<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>
|-
|<code>timeZoneOffset</code>
|string
|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">"timeZoneOffset": "UTC+01:00"</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>
|-
|<code>resellers</code>
|string
|yes
|The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] location URI the person belongs 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">"belongsToCustomerId": 4000002</source>
|-
|<code>customers</code>
|string
|yes
|The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] location URI the person belongs 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">"externalId": 987654321</source>
|-
|[[stoney_core:_REST_API#Error_codes_and_responses|<code>error</code>]]
|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 information.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>
|}
== Person update (PUT) ==
To updates an existing person, the client needs to send a HTTP <code>PUT</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 an empty body.
The <code>PUT</code> method requires one to sent the complete record, thus the work-flow is normally as follows:
# A [[#Person_element_retrieval_.28GET.29|GET]] request on the Person element URI will be made to fetch the whole document.
# Update the fields which content has changed
# Send a <code>PUT</code> request with all the person data
=== Person update request message ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP request part
! Content
! Example
|-
| Request lines
|<pre>
PUT <Request-URI> HTTP 1.1
HOST: <Host>
</pre>
|<pre>
PUT /v1/people/5000001 HTTP 1.1
HOST: api.example.com
</pre>
|-
| Request headers
| <pre>
Accept: <Type>/<Subtype>
Accept-Charset: <Charset>
Content-Type: <Type>/<Subtype>; charset=<Charset>
</pre>
| <pre>
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json; charset=UTF-8
</pre>
|-
| [[#Person_update_request_message_body|Request body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== Person update request message body ====
See [[#person_object|Person object]].
=== Person update response message ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP response part
! Content
! Example
|-
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 200 OK</pre>
|-
| Response headers
|<pre>
Content-Type: <Type>/<Subtype>; charset=<Charset>
</pre>
|<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
</pre>
|-
| [[#Person_update_response_message_body|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== 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 information about the failure.
== Person partly update (PATCH) ==
To update fields of an existing person, the client needs to send a HTTP <code>PATCH</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 an empty body.
In contrast to the [[#Person_update_.28PUT.29|<code>PUT</code>]] method, only the changed fields are to be included in the request.
=== Person partly update request message ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP request part
! Content
! Example
|-
| Request lines
|<pre>
PATCH <Request-URI> HTTP 1.1
HOST: <Host>
</pre>
|<pre>
PATCH /v1/people/5000001 HTTP 1.1
HOST: api.example.com
</pre>
|-
| Request headers
| <pre>
Accept: <Type>/<Subtype>
Accept-Charset: <Charset>
Content-Type: <Type>/<Subtype>; charset=<Charset>
</pre>
| <pre>
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json; charset=UTF-8
</pre>
|-
| [[#Person_update_request_message_body|Request body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== 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 ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP response part
! Content
! Example
|-
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 200 OK</pre>
|-
| Response headers
|<pre>
Content-Type: <Type>/<Subtype>; charset=<Charset>
</pre>
|<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
</pre>
|-
| [[#Person_partly_update_response_message_body|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== 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 information about the failure.
== Person deletion (DELETE) ==
To delete an existing person, the client needs to send a HTTP <code>DELETE</code> request, with an empty request body 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 <code>200</code> (OK) on success and returns an empty body.
=== Person deletion request message ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP request part
! Content
! Example
|-
| Request lines
|<pre>
DELETE <Request-URI> HTTP 1.1
HOST: <Host>
</pre>
|<pre>
DELETE /v1/people/5000001 HTTP 1.1
HOST: api.example.com
</pre>
|-
| Request headers
| <pre>
Accept: <Type>/<Subtype>
Accept-Charset: <Charset>
</pre>
| <pre>
Accept: application/json
Accept-Charset: UTF-8
</pre>
|-
| Request body
| <Empty>
| <pre></pre>
|}
=== Person deletion response message ===
{| class="wikitable sortable" style="width: 100%;"
|-
! HTTP response part
! Content
! Example
|-
| Status Line
| <pre>HTTP/1.1 <HTTP-Status-Code> <HTTP-Status-Message></pre>
| <pre>HTTP/1.1 200 OK</pre>
|-
| Response headers
|<pre>
Content-Type: <Type>/<Subtype>; charset=<Charset>
</pre>
|<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
</pre>
|-
| [[#Person_partly_update_response_message_body|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>
|}
==== 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 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 =
* [[stoney core: REST API]]
Hello world!
[[Category:REST API]][[Category:stoney core]]
