stoney-cloud.org - User contributions [en]

stoney cloud: Upgrade

2015-03-17T09:17:09Z

Chrigu: /* Basic Testing Steps */

= Overview =
This guide explains, what you need to do during the installation of your Multi-Node Installation.

== Prepare your stoney cloud installation for the update ==

=== <= 1.2.10.3 ===

If you have a '''productive''' (releases) stoney cloud Installation, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/releases/1.2/packages"' >> /etc/portage/make.conf
</source>

If you have a '''test''' (pre-releases) stoney cloud Installation instead, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf
</source>

'''IMPORTANT:''' Even a pre-release ISO may result in a stable installation, depending on when it was generated in the release cycle. Please verify by executing <code>git branch</code> in <code>/usr/portage</code> and <code>/var/lib/layman/foss-cloud</code> whether this is the case, and [[stoney_cloud:_Switch_to_testing_branch|switch to the testing branch]] if needed (that is: if the branch displayed does not contain the words <code>pre</code> or <code>testing</code>. If the branch is empty, that means you have a brand new installation without anything yet. In that case, directly check the configuration files <code>/usr/portage/.git/config</code> and/or <code>/var/lib/layman/foss-cloud/.git/config</code> to see which branch it would check out upon <code>emerge --sync</code> and from where.).

=== >= 1.2.10.4 ===

Execute the following command to register the binary package mirror (since for now there will be only pre-releases, but with better quality than FOSS-Cloud releases):

<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf

# Disable the SYNC from rsync since newer portage versions otherwise won't accept a portage tree via git
sed -i -e 's|^SYNC|#SYNC|' /etc/portage/make.conf
</source>

== Update ==

=== Updating from 1.2.10.7 or earlier to 1.2.10.8_rc4 or newer ===

A complete rebuild of all packages was required, therefore the update guide is different:

<source lang='bash'>
emerge --sync

emerge -eK world -va

# sst-libvirt-hooks is not part of the stoney-cloud anymore since it requires further configuration
# make sure that it still gets updated and not removed later, if you have it installed and enabled
emerge -K app-emulation/sst-libvirt-hooks

dispatch-conf

# Switch runtime switchable options
eselect python set python3.3
eselect php set cli php5.5
eselect php set apache2 php5.5
gcc-config x86_64-pc-linux-gnu-4.7.3
</source>

During the dispatch-conf the following may appear:
* /etc/libvirt/libvirt.conf: you may get the suggestion to remove almost all content. Quit dispatch-conf and do: <code>rm /etc/libvirt/._mrg*</code> and start dispatch-conf again.
* /etc/libvirt/libvirt.conf: merge all whitespace/comment changes but make sure you don't overwrite the <code>listen_addr</code>
* /etc/portage/make.conf: merge all changes beside the <code>PORTAGE_BINHOST</code>
* /var/www/localhost/htdocs/vm-manager/vm_config.php: merge the versions, newly added lines and comments. Avoid changes on sstSourceHostName array

To make sure everything works, reboot and then cleanup:

<source lang='bash'>
emerge --depclean -va
</source>

* If the cleanup fails stating that <code>Locale-gettext</code> and <code>dev-libs/boost</code> depends on some version of perl, reinstall that package manually once and try again:
<source lang='bash'>
emerge -1Kva dev-libs/boost Locale-gettext

# same for autoconf-/automake-wrapper if host was used to build stuff:
emerge -1K sys-devel/autoconf-wrapper sys-devel/automake-wrapper
</source>
* '''WARNING''': this also removes the current kernel. If you want to play it safe, reboot first, then depclean, then reboot again
* Rebuilde separately installed perl modules and remove traces of the old perl version:
<source lang='bash'>
perl-cleaner --all -- -va
rm -rf /usr/lib64/perl5/{vendor_perl,}/5.12.4
</source>

==== Emulator ====
* u=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,o=stepping-stone,c=ch

Change
<pre>
sstEmulator: /usr/bin/qemu-kvm
</pre>
to
<pre>
sstEmulator: /usr/bin/qemu-system-x86_64
</pre>

==== Source Port ====
* sstDisk=vda,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org
* sstDisk=vdb,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org

Add
<pre>
sstSourcePort: 24007
</pre>

==== Firewall / Subversion ====
If you are using our firewall scripts (libvirt-hooks based), you'll also have to upgrade subversion (on all the stoney cloud nodes):
<source lang='bash'>
cd /usr/local/scripts/netfilter/local/chains/vms
svn upgrade
cd /usr/local/scripts/netfilter/local/chains/$(hostname -s)
svn upgrade
</source>

=== Regular Update ===

Makes sure, your local portage tree is updated:
emerge --sync

Now you can make sure, that you've got the current stoney cloud version installed:
emerge -KuDva virtual/foss-cloud

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!

Total: 0 packages, Size of downloads: 0 kB

* virtual/foss-cloud-1.2.10.4

Would you like to add these packages to your world favorites? [Yes/No] '''no'''
</pre>

If you have updated you stoney cloud, you might want to sanely update your configuration files after emerging new packages (including updates):
dispatch-conf

== Installing Software Examples ==
Per default, the stoney cloud expects you to install binary packages. So if you don't pass any special parameters to the emerge command, the binary package (if it exists) will be used.

=== Binary Package ===
Per default, the stoney cloud expects you to install binary packages, which can be seen with '''[binary R ]''' output.
emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[binary R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 5,295 kB

Total: 1 package (1 reinstall, 1 binary), Size of downloads: 5,295 kB

Would you like to merge these packages? [Yes/No] no

Quitting.
</pre>

=== Force Non-Binary Package ===
If you force a non-binary package, the output will be in the form of '''[ebuild R ]'''.
FEATURES="-getbinpkg" emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] app-arch/cpio-2.11 USE="nls" 995 kB
[ebuild R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 4,523 kB

Total: 2 packages (1 new, 1 reinstall), Size of downloads: 5,518 kB

Would you like to merge these packages? [Yes/No]
</pre>

=== No Binary Package Exists ===
The following example shows you a package with no existing binary package, therefore the package must be compiled on the fly, shown with '''[ebuild N ]'''.
emerge -va htop

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] sys-process/htop-1.0.2 USE="unicode -openvz -vserver" 380 kB

Total: 1 package (1 new), Size of downloads: 380 kB

Would you like to merge these packages? [Yes/No]
</pre>

== Multi-Node Installation ==
Follow the [[Multi-Node_Installation#Specialized_Installation | Specialized Installation]] Guide.

== Basic Testing Steps ==
Get your stoney cloud image:
<source lang='bash'>
version=1.2.10.7 # stoney cloud version

cd /var/virtualization/iso-choosable/
wget http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/iso/foss-cloud-installer-${version}.iso
chown apache:vm-storage foss-cloud-installer-${version}.iso
chmod 644 foss-cloud-installer-${version}.iso
</source>

Get the [http://www.sysresccd.org/SystemRescueCd_Homepage SystemRescueCd] ISO:
<source lang='bash'>
version=4.5.1 # SystemRescueCd version
sha256="4fda2fce55a46c7b258fba10c88a4a337821c8b801a8cd3c344cc223a9c4436d" # SHA256 checksum of the ISO
isoFile="systemrescuecd-x86-${version}.iso"

cd /var/virtualization/iso-choosable/

wget http://sourceforge.net/projects/systemrescuecd/files/sysresccd-x86/${version}/${isoFile}

# Check that the file was downloaded correctly
echo "${sha256} ${isoFile}" | sha256sum -c -

chown apache:vm-storage ${isoFile}
chmod 644 ${isoFile}
</source>

Get a Fedora ISO image:
<source lang='bash'>
version=21 # Fedora version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/fedora/linux/releases/${version}/Server/x86_64/iso/Fedora-Server-netinst-x86_64-${version}.iso
chown apache:vm-storage Fedora-Server-netinst-x86_64-${version}.iso
chmod 644 Fedora-Server-netinst-x86_64-${version}.iso
</source>

Lernstick (Test):
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://www.imedias.ch/dateien/lernstick-testversion/lernstick_debian7_2013-12-12.iso
chown apache:vm-storage lernstick_debian7_2013-12-12.iso
chmod 644 lernstick_debian7_2013-12-12.iso
</source>

Get your debian image:
<source lang='bash'>
version=7.8.0 # Debian version

cd /var/virtualization/iso-choosable/
wget http://cdimage.debian.org/debian-cd/${version}/amd64/iso-cd/debian-${version}-amd64-netinst.iso
chown apache:vm-storage debian-${version}-amd64-netinst.iso
chmod 644 debian-${version}-amd64-netinst.iso
</source>

Get your ubuntu desktop image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-desktop-amd64.iso
chown apache:vm-storage ubuntu-${version}-desktop-amd64.iso
chmod 644 ubuntu-${version}-desktop-amd64.iso
</source>

Get your ubuntu server image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-server-amd64.iso
chown apache:vm-storage ubuntu-${version}-server-amd64.iso
chmod 644 ubuntu-${version}-server-amd64.iso
</source>

Get a Windows 2012 Server R2 ISO image:
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://care.dlservice.microsoft.com/dl/download/6/2/A/62A76ABB-9990-4EFC-A4FE-C7D698DAEB96/9600.17050.WINBLUE_REFRESH.140317-1640_X64FRE_SERVER_EVAL_EN-US-IR3_SSS_X64FREE_EN-US_DV9.ISO -O windows_server_2012_r2_64bit_en.iso
chown apache:vm-storage windows_server_2012_r2_64bit_en.iso
chmod 644 windows_server_2012_r2_64bit_en.iso
</source>

If you need the newest Windows Drivers ISO image, visit http://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/

Set three network ranges under https://192.168.140.10/vm-manager/subnet/index.html
192.168.140.64
26
Template Range
template

192.168.140.128
26
Persistent Range
persistent

192.168.140.192
26
Dynamic Range
dynamic

Add the three newly creates network ranges to the VM-Pools under https://192.168.140.10/vm-manager/vmPool/index.html

Create a Virtual Machine Profile under https://192.168.140.10/vm-manager/vmProfile/create.html

Create a Virtual Machine Template under https://192.168.140.10/vm-manager/vmTemplate/create.html and install a basic operating system.

Create a persistent Virtual Machine from the newly created Virtual Machine Template.

== Known Issues ==
None.

[[Category:Installation]]
[[Category:stoney cloud]]

stoney cloud: Upgrade

2015-03-17T09:15:31Z

Chrigu: /* Basic Testing Steps */

= Overview =
This guide explains, what you need to do during the installation of your Multi-Node Installation.

== Prepare your stoney cloud installation for the update ==

=== <= 1.2.10.3 ===

If you have a '''productive''' (releases) stoney cloud Installation, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/releases/1.2/packages"' >> /etc/portage/make.conf
</source>

If you have a '''test''' (pre-releases) stoney cloud Installation instead, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf
</source>

'''IMPORTANT:''' Even a pre-release ISO may result in a stable installation, depending on when it was generated in the release cycle. Please verify by executing <code>git branch</code> in <code>/usr/portage</code> and <code>/var/lib/layman/foss-cloud</code> whether this is the case, and [[stoney_cloud:_Switch_to_testing_branch|switch to the testing branch]] if needed (that is: if the branch displayed does not contain the words <code>pre</code> or <code>testing</code>. If the branch is empty, that means you have a brand new installation without anything yet. In that case, directly check the configuration files <code>/usr/portage/.git/config</code> and/or <code>/var/lib/layman/foss-cloud/.git/config</code> to see which branch it would check out upon <code>emerge --sync</code> and from where.).

=== >= 1.2.10.4 ===

Execute the following command to register the binary package mirror (since for now there will be only pre-releases, but with better quality than FOSS-Cloud releases):

<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf

# Disable the SYNC from rsync since newer portage versions otherwise won't accept a portage tree via git
sed -i -e 's|^SYNC|#SYNC|' /etc/portage/make.conf
</source>

== Update ==

=== Updating from 1.2.10.7 or earlier to 1.2.10.8_rc4 or newer ===

A complete rebuild of all packages was required, therefore the update guide is different:

<source lang='bash'>
emerge --sync

emerge -eK world -va

# sst-libvirt-hooks is not part of the stoney-cloud anymore since it requires further configuration
# make sure that it still gets updated and not removed later, if you have it installed and enabled
emerge -K app-emulation/sst-libvirt-hooks

dispatch-conf

# Switch runtime switchable options
eselect python set python3.3
eselect php set cli php5.5
eselect php set apache2 php5.5
gcc-config x86_64-pc-linux-gnu-4.7.3
</source>

During the dispatch-conf the following may appear:
* /etc/libvirt/libvirt.conf: you may get the suggestion to remove almost all content. Quit dispatch-conf and do: <code>rm /etc/libvirt/._mrg*</code> and start dispatch-conf again.
* /etc/libvirt/libvirt.conf: merge all whitespace/comment changes but make sure you don't overwrite the <code>listen_addr</code>
* /etc/portage/make.conf: merge all changes beside the <code>PORTAGE_BINHOST</code>
* /var/www/localhost/htdocs/vm-manager/vm_config.php: merge the versions, newly added lines and comments. Avoid changes on sstSourceHostName array

To make sure everything works, reboot and then cleanup:

<source lang='bash'>
emerge --depclean -va
</source>

* If the cleanup fails stating that <code>Locale-gettext</code> and <code>dev-libs/boost</code> depends on some version of perl, reinstall that package manually once and try again:
<source lang='bash'>
emerge -1Kva dev-libs/boost Locale-gettext

# same for autoconf-/automake-wrapper if host was used to build stuff:
emerge -1K sys-devel/autoconf-wrapper sys-devel/automake-wrapper
</source>
* '''WARNING''': this also removes the current kernel. If you want to play it safe, reboot first, then depclean, then reboot again
* Rebuilde separately installed perl modules and remove traces of the old perl version:
<source lang='bash'>
perl-cleaner --all -- -va
rm -rf /usr/lib64/perl5/{vendor_perl,}/5.12.4
</source>

==== Emulator ====
* u=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,o=stepping-stone,c=ch

Change
<pre>
sstEmulator: /usr/bin/qemu-kvm
</pre>
to
<pre>
sstEmulator: /usr/bin/qemu-system-x86_64
</pre>

==== Source Port ====
* sstDisk=vda,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org
* sstDisk=vdb,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org

Add
<pre>
sstSourcePort: 24007
</pre>

==== Firewall / Subversion ====
If you are using our firewall scripts (libvirt-hooks based), you'll also have to upgrade subversion (on all the stoney cloud nodes):
<source lang='bash'>
cd /usr/local/scripts/netfilter/local/chains/vms
svn upgrade
cd /usr/local/scripts/netfilter/local/chains/$(hostname -s)
svn upgrade
</source>

=== Regular Update ===

Makes sure, your local portage tree is updated:
emerge --sync

Now you can make sure, that you've got the current stoney cloud version installed:
emerge -KuDva virtual/foss-cloud

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!

Total: 0 packages, Size of downloads: 0 kB

* virtual/foss-cloud-1.2.10.4

Would you like to add these packages to your world favorites? [Yes/No] '''no'''
</pre>

If you have updated you stoney cloud, you might want to sanely update your configuration files after emerging new packages (including updates):
dispatch-conf

== Installing Software Examples ==
Per default, the stoney cloud expects you to install binary packages. So if you don't pass any special parameters to the emerge command, the binary package (if it exists) will be used.

=== Binary Package ===
Per default, the stoney cloud expects you to install binary packages, which can be seen with '''[binary R ]''' output.
emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[binary R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 5,295 kB

Total: 1 package (1 reinstall, 1 binary), Size of downloads: 5,295 kB

Would you like to merge these packages? [Yes/No] no

Quitting.
</pre>

=== Force Non-Binary Package ===
If you force a non-binary package, the output will be in the form of '''[ebuild R ]'''.
FEATURES="-getbinpkg" emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] app-arch/cpio-2.11 USE="nls" 995 kB
[ebuild R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 4,523 kB

Total: 2 packages (1 new, 1 reinstall), Size of downloads: 5,518 kB

Would you like to merge these packages? [Yes/No]
</pre>

=== No Binary Package Exists ===
The following example shows you a package with no existing binary package, therefore the package must be compiled on the fly, shown with '''[ebuild N ]'''.
emerge -va htop

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] sys-process/htop-1.0.2 USE="unicode -openvz -vserver" 380 kB

Total: 1 package (1 new), Size of downloads: 380 kB

Would you like to merge these packages? [Yes/No]
</pre>

== Multi-Node Installation ==
Follow the [[Multi-Node_Installation#Specialized_Installation | Specialized Installation]] Guide.

== Basic Testing Steps ==
Get your stoney cloud image:
<source lang='bash'>
version=1.2.10.7 # stoney cloud version

cd /var/virtualization/iso-choosable/
wget http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/iso/foss-cloud-installer-${version}.iso
chown apache:vm-storage foss-cloud-installer-${version}.iso
chmod 644 foss-cloud-installer-${version}.iso
</source>

Get the [http://www.sysresccd.org/SystemRescueCd_Homepage SystemRescueCd] ISO:
<source lang='bash'>
version=4.5.1 # SystemRescueCd version
sha256="4fda2fce55a46c7b258fba10c88a4a337821c8b801a8cd3c344cc223a9c4436d" # SHA256 checksum of the ISO

cd /var/virtualization/iso-choosable/

wget http://sourceforge.net/projects/systemrescuecd/files/sysresccd-x86/${version}/systemrescuecd-x86-${version}.iso

# Check that the file was downloaded correctly
echo "${sha256} systemrescuecd-x86-${version}.iso" | sha256sum -c -

chown apache:vm-storage systemrescuecd-x86-${version}.iso
chmod 644 systemrescuecd-x86-${version}.iso
</source>

Get a Fedora ISO image:
<source lang='bash'>
version=21 # Fedora version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/fedora/linux/releases/${version}/Server/x86_64/iso/Fedora-Server-netinst-x86_64-${version}.iso
chown apache:vm-storage Fedora-Server-netinst-x86_64-${version}.iso
chmod 644 Fedora-Server-netinst-x86_64-${version}.iso
</source>

Lernstick (Test):
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://www.imedias.ch/dateien/lernstick-testversion/lernstick_debian7_2013-12-12.iso
chown apache:vm-storage lernstick_debian7_2013-12-12.iso
chmod 644 lernstick_debian7_2013-12-12.iso
</source>

Get your debian image:
<source lang='bash'>
version=7.8.0 # Debian version

cd /var/virtualization/iso-choosable/
wget http://cdimage.debian.org/debian-cd/${version}/amd64/iso-cd/debian-${version}-amd64-netinst.iso
chown apache:vm-storage debian-${version}-amd64-netinst.iso
chmod 644 debian-${version}-amd64-netinst.iso
</source>

Get your ubuntu desktop image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-desktop-amd64.iso
chown apache:vm-storage ubuntu-${version}-desktop-amd64.iso
chmod 644 ubuntu-${version}-desktop-amd64.iso
</source>

Get your ubuntu server image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-server-amd64.iso
chown apache:vm-storage ubuntu-${version}-server-amd64.iso
chmod 644 ubuntu-${version}-server-amd64.iso
</source>

Get a Windows 2012 Server R2 ISO image:
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://care.dlservice.microsoft.com/dl/download/6/2/A/62A76ABB-9990-4EFC-A4FE-C7D698DAEB96/9600.17050.WINBLUE_REFRESH.140317-1640_X64FRE_SERVER_EVAL_EN-US-IR3_SSS_X64FREE_EN-US_DV9.ISO -O windows_server_2012_r2_64bit_en.iso
chown apache:vm-storage windows_server_2012_r2_64bit_en.iso
chmod 644 windows_server_2012_r2_64bit_en.iso
</source>

If you need the newest Windows Drivers ISO image, visit http://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/

Set three network ranges under https://192.168.140.10/vm-manager/subnet/index.html
192.168.140.64
26
Template Range
template

192.168.140.128
26
Persistent Range
persistent

192.168.140.192
26
Dynamic Range
dynamic

Add the three newly creates network ranges to the VM-Pools under https://192.168.140.10/vm-manager/vmPool/index.html

Create a Virtual Machine Profile under https://192.168.140.10/vm-manager/vmProfile/create.html

Create a Virtual Machine Template under https://192.168.140.10/vm-manager/vmTemplate/create.html and install a basic operating system.

Create a persistent Virtual Machine from the newly created Virtual Machine Template.

== Known Issues ==
None.

[[Category:Installation]]
[[Category:stoney cloud]]

stoney cloud: Upgrade

2015-03-17T09:14:01Z

Chrigu: /* Basic Testing Steps */

= Overview =
This guide explains, what you need to do during the installation of your Multi-Node Installation.

== Prepare your stoney cloud installation for the update ==

=== <= 1.2.10.3 ===

If you have a '''productive''' (releases) stoney cloud Installation, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/releases/1.2/packages"' >> /etc/portage/make.conf
</source>

If you have a '''test''' (pre-releases) stoney cloud Installation instead, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf
</source>

'''IMPORTANT:''' Even a pre-release ISO may result in a stable installation, depending on when it was generated in the release cycle. Please verify by executing <code>git branch</code> in <code>/usr/portage</code> and <code>/var/lib/layman/foss-cloud</code> whether this is the case, and [[stoney_cloud:_Switch_to_testing_branch|switch to the testing branch]] if needed (that is: if the branch displayed does not contain the words <code>pre</code> or <code>testing</code>. If the branch is empty, that means you have a brand new installation without anything yet. In that case, directly check the configuration files <code>/usr/portage/.git/config</code> and/or <code>/var/lib/layman/foss-cloud/.git/config</code> to see which branch it would check out upon <code>emerge --sync</code> and from where.).

=== >= 1.2.10.4 ===

Execute the following command to register the binary package mirror (since for now there will be only pre-releases, but with better quality than FOSS-Cloud releases):

<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf

# Disable the SYNC from rsync since newer portage versions otherwise won't accept a portage tree via git
sed -i -e 's|^SYNC|#SYNC|' /etc/portage/make.conf
</source>

== Update ==

=== Updating from 1.2.10.7 or earlier to 1.2.10.8_rc4 or newer ===

A complete rebuild of all packages was required, therefore the update guide is different:

<source lang='bash'>
emerge --sync

emerge -eK world -va

# sst-libvirt-hooks is not part of the stoney-cloud anymore since it requires further configuration
# make sure that it still gets updated and not removed later, if you have it installed and enabled
emerge -K app-emulation/sst-libvirt-hooks

dispatch-conf

# Switch runtime switchable options
eselect python set python3.3
eselect php set cli php5.5
eselect php set apache2 php5.5
gcc-config x86_64-pc-linux-gnu-4.7.3
</source>

During the dispatch-conf the following may appear:
* /etc/libvirt/libvirt.conf: you may get the suggestion to remove almost all content. Quit dispatch-conf and do: <code>rm /etc/libvirt/._mrg*</code> and start dispatch-conf again.
* /etc/libvirt/libvirt.conf: merge all whitespace/comment changes but make sure you don't overwrite the <code>listen_addr</code>
* /etc/portage/make.conf: merge all changes beside the <code>PORTAGE_BINHOST</code>
* /var/www/localhost/htdocs/vm-manager/vm_config.php: merge the versions, newly added lines and comments. Avoid changes on sstSourceHostName array

To make sure everything works, reboot and then cleanup:

<source lang='bash'>
emerge --depclean -va
</source>

* If the cleanup fails stating that <code>Locale-gettext</code> and <code>dev-libs/boost</code> depends on some version of perl, reinstall that package manually once and try again:
<source lang='bash'>
emerge -1Kva dev-libs/boost Locale-gettext

# same for autoconf-/automake-wrapper if host was used to build stuff:
emerge -1K sys-devel/autoconf-wrapper sys-devel/automake-wrapper
</source>
* '''WARNING''': this also removes the current kernel. If you want to play it safe, reboot first, then depclean, then reboot again
* Rebuilde separately installed perl modules and remove traces of the old perl version:
<source lang='bash'>
perl-cleaner --all -- -va
rm -rf /usr/lib64/perl5/{vendor_perl,}/5.12.4
</source>

==== Emulator ====
* u=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,o=stepping-stone,c=ch

Change
<pre>
sstEmulator: /usr/bin/qemu-kvm
</pre>
to
<pre>
sstEmulator: /usr/bin/qemu-system-x86_64
</pre>

==== Source Port ====
* sstDisk=vda,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org
* sstDisk=vdb,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org

Add
<pre>
sstSourcePort: 24007
</pre>

==== Firewall / Subversion ====
If you are using our firewall scripts (libvirt-hooks based), you'll also have to upgrade subversion (on all the stoney cloud nodes):
<source lang='bash'>
cd /usr/local/scripts/netfilter/local/chains/vms
svn upgrade
cd /usr/local/scripts/netfilter/local/chains/$(hostname -s)
svn upgrade
</source>

=== Regular Update ===

Makes sure, your local portage tree is updated:
emerge --sync

Now you can make sure, that you've got the current stoney cloud version installed:
emerge -KuDva virtual/foss-cloud

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!

Total: 0 packages, Size of downloads: 0 kB

* virtual/foss-cloud-1.2.10.4

Would you like to add these packages to your world favorites? [Yes/No] '''no'''
</pre>

If you have updated you stoney cloud, you might want to sanely update your configuration files after emerging new packages (including updates):
dispatch-conf

== Installing Software Examples ==
Per default, the stoney cloud expects you to install binary packages. So if you don't pass any special parameters to the emerge command, the binary package (if it exists) will be used.

=== Binary Package ===
Per default, the stoney cloud expects you to install binary packages, which can be seen with '''[binary R ]''' output.
emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[binary R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 5,295 kB

Total: 1 package (1 reinstall, 1 binary), Size of downloads: 5,295 kB

Would you like to merge these packages? [Yes/No] no

Quitting.
</pre>

=== Force Non-Binary Package ===
If you force a non-binary package, the output will be in the form of '''[ebuild R ]'''.
FEATURES="-getbinpkg" emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] app-arch/cpio-2.11 USE="nls" 995 kB
[ebuild R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 4,523 kB

Total: 2 packages (1 new, 1 reinstall), Size of downloads: 5,518 kB

Would you like to merge these packages? [Yes/No]
</pre>

=== No Binary Package Exists ===
The following example shows you a package with no existing binary package, therefore the package must be compiled on the fly, shown with '''[ebuild N ]'''.
emerge -va htop

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] sys-process/htop-1.0.2 USE="unicode -openvz -vserver" 380 kB

Total: 1 package (1 new), Size of downloads: 380 kB

Would you like to merge these packages? [Yes/No]
</pre>

== Multi-Node Installation ==
Follow the [[Multi-Node_Installation#Specialized_Installation | Specialized Installation]] Guide.

== Basic Testing Steps ==
Get your stoney cloud image:
<source lang='bash'>
version=1.2.10.7 # stoney cloud version

cd /var/virtualization/iso-choosable/
wget http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/iso/foss-cloud-installer-${version}.iso
chown apache:vm-storage foss-cloud-installer-${version}.iso
chmod 644 foss-cloud-installer-${version}.iso
</source>

Get the [http://www.sysresccd.org/SystemRescueCd_Homepage SystemRescueCd] ISO:
<source lang='bash'>
version=4.5.1 # SystemRescueCd version

cd /var/virtualization/iso-choosable/

wget http://sourceforge.net/projects/systemrescuecd/files/sysresccd-x86/${version}/systemrescuecd-x86-${version}.iso

# Check that the file was downloaded correctly
echo "93e689d218f412d0096da26053ea9828aa5dc7b6 systemrescuecd-x86-${version}.iso" | sha1sum -c -

chown apache:vm-storage systemrescuecd-x86-${version}.iso
chmod 644 systemrescuecd-x86-${version}.iso
</source>

Get a Fedora ISO image:
<source lang='bash'>
version=21 # Fedora version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/fedora/linux/releases/${version}/Server/x86_64/iso/Fedora-Server-netinst-x86_64-${version}.iso
chown apache:vm-storage Fedora-Server-netinst-x86_64-${version}.iso
chmod 644 Fedora-Server-netinst-x86_64-${version}.iso
</source>

Lernstick (Test):
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://www.imedias.ch/dateien/lernstick-testversion/lernstick_debian7_2013-12-12.iso
chown apache:vm-storage lernstick_debian7_2013-12-12.iso
chmod 644 lernstick_debian7_2013-12-12.iso
</source>

Get your debian image:
<source lang='bash'>
version=7.8.0 # Debian version

cd /var/virtualization/iso-choosable/
wget http://cdimage.debian.org/debian-cd/${version}/amd64/iso-cd/debian-${version}-amd64-netinst.iso
chown apache:vm-storage debian-${version}-amd64-netinst.iso
chmod 644 debian-${version}-amd64-netinst.iso
</source>

Get your ubuntu desktop image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-desktop-amd64.iso
chown apache:vm-storage ubuntu-${version}-desktop-amd64.iso
chmod 644 ubuntu-${version}-desktop-amd64.iso
</source>

Get your ubuntu server image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-server-amd64.iso
chown apache:vm-storage ubuntu-${version}-server-amd64.iso
chmod 644 ubuntu-${version}-server-amd64.iso
</source>

Get a Windows 2012 Server R2 ISO image:
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://care.dlservice.microsoft.com/dl/download/6/2/A/62A76ABB-9990-4EFC-A4FE-C7D698DAEB96/9600.17050.WINBLUE_REFRESH.140317-1640_X64FRE_SERVER_EVAL_EN-US-IR3_SSS_X64FREE_EN-US_DV9.ISO -O windows_server_2012_r2_64bit_en.iso
chown apache:vm-storage windows_server_2012_r2_64bit_en.iso
chmod 644 windows_server_2012_r2_64bit_en.iso
</source>

If you need the newest Windows Drivers ISO image, visit http://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/

Set three network ranges under https://192.168.140.10/vm-manager/subnet/index.html
192.168.140.64
26
Template Range
template

192.168.140.128
26
Persistent Range
persistent

192.168.140.192
26
Dynamic Range
dynamic

Add the three newly creates network ranges to the VM-Pools under https://192.168.140.10/vm-manager/vmPool/index.html

Create a Virtual Machine Profile under https://192.168.140.10/vm-manager/vmProfile/create.html

Create a Virtual Machine Template under https://192.168.140.10/vm-manager/vmTemplate/create.html and install a basic operating system.

Create a persistent Virtual Machine from the newly created Virtual Machine Template.

== Known Issues ==
None.

[[Category:Installation]]
[[Category:stoney cloud]]

stoney cloud: Upgrade

2015-03-17T08:59:20Z

Chrigu: /* Basic Testing Steps */

= Overview =
This guide explains, what you need to do during the installation of your Multi-Node Installation.

== Prepare your stoney cloud installation for the update ==

=== <= 1.2.10.3 ===

If you have a '''productive''' (releases) stoney cloud Installation, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/releases/1.2/packages"' >> /etc/portage/make.conf
</source>

If you have a '''test''' (pre-releases) stoney cloud Installation instead, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf
</source>

'''IMPORTANT:''' Even a pre-release ISO may result in a stable installation, depending on when it was generated in the release cycle. Please verify by executing <code>git branch</code> in <code>/usr/portage</code> and <code>/var/lib/layman/foss-cloud</code> whether this is the case, and [[stoney_cloud:_Switch_to_testing_branch|switch to the testing branch]] if needed (that is: if the branch displayed does not contain the words <code>pre</code> or <code>testing</code>. If the branch is empty, that means you have a brand new installation without anything yet. In that case, directly check the configuration files <code>/usr/portage/.git/config</code> and/or <code>/var/lib/layman/foss-cloud/.git/config</code> to see which branch it would check out upon <code>emerge --sync</code> and from where.).

=== >= 1.2.10.4 ===

Execute the following command to register the binary package mirror (since for now there will be only pre-releases, but with better quality than FOSS-Cloud releases):

<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf

# Disable the SYNC from rsync since newer portage versions otherwise won't accept a portage tree via git
sed -i -e 's|^SYNC|#SYNC|' /etc/portage/make.conf
</source>

== Update ==

=== Updating from 1.2.10.7 or earlier to 1.2.10.8_rc4 or newer ===

A complete rebuild of all packages was required, therefore the update guide is different:

<source lang='bash'>
emerge --sync

emerge -eK world -va

# sst-libvirt-hooks is not part of the stoney-cloud anymore since it requires further configuration
# make sure that it still gets updated and not removed later, if you have it installed and enabled
emerge -K app-emulation/sst-libvirt-hooks

dispatch-conf

# Switch runtime switchable options
eselect python set python3.3
eselect php set cli php5.5
eselect php set apache2 php5.5
gcc-config x86_64-pc-linux-gnu-4.7.3
</source>

During the dispatch-conf the following may appear:
* /etc/libvirt/libvirt.conf: you may get the suggestion to remove almost all content. Quit dispatch-conf and do: <code>rm /etc/libvirt/._mrg*</code> and start dispatch-conf again.
* /etc/libvirt/libvirt.conf: merge all whitespace/comment changes but make sure you don't overwrite the <code>listen_addr</code>
* /etc/portage/make.conf: merge all changes beside the <code>PORTAGE_BINHOST</code>
* /var/www/localhost/htdocs/vm-manager/vm_config.php: merge the versions, newly added lines and comments. Avoid changes on sstSourceHostName array

To make sure everything works, reboot and then cleanup:

<source lang='bash'>
emerge --depclean -va
</source>

* If the cleanup fails stating that <code>Locale-gettext</code> and <code>dev-libs/boost</code> depends on some version of perl, reinstall that package manually once and try again:
<source lang='bash'>
emerge -1Kva dev-libs/boost Locale-gettext

# same for autoconf-/automake-wrapper if host was used to build stuff:
emerge -1K sys-devel/autoconf-wrapper sys-devel/automake-wrapper
</source>
* '''WARNING''': this also removes the current kernel. If you want to play it safe, reboot first, then depclean, then reboot again
* Rebuilde separately installed perl modules and remove traces of the old perl version:
<source lang='bash'>
perl-cleaner --all -- -va
rm -rf /usr/lib64/perl5/{vendor_perl,}/5.12.4
</source>

==== Emulator ====
* u=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,o=stepping-stone,c=ch

Change
<pre>
sstEmulator: /usr/bin/qemu-kvm
</pre>
to
<pre>
sstEmulator: /usr/bin/qemu-system-x86_64
</pre>

==== Source Port ====
* sstDisk=vda,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org
* sstDisk=vdb,ou=devices,sstVirtualMachine=*,ou=virtual machines,ou=virtualization,ou=services,dc=stoney-cloud,dc=org

Add
<pre>
sstSourcePort: 24007
</pre>

==== Firewall / Subversion ====
If you are using our firewall scripts (libvirt-hooks based), you'll also have to upgrade subversion (on all the stoney cloud nodes):
<source lang='bash'>
cd /usr/local/scripts/netfilter/local/chains/vms
svn upgrade
cd /usr/local/scripts/netfilter/local/chains/$(hostname -s)
svn upgrade
</source>

=== Regular Update ===

Makes sure, your local portage tree is updated:
emerge --sync

Now you can make sure, that you've got the current stoney cloud version installed:
emerge -KuDva virtual/foss-cloud

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!

Total: 0 packages, Size of downloads: 0 kB

* virtual/foss-cloud-1.2.10.4

Would you like to add these packages to your world favorites? [Yes/No] '''no'''
</pre>

If you have updated you stoney cloud, you might want to sanely update your configuration files after emerging new packages (including updates):
dispatch-conf

== Installing Software Examples ==
Per default, the stoney cloud expects you to install binary packages. So if you don't pass any special parameters to the emerge command, the binary package (if it exists) will be used.

=== Binary Package ===
Per default, the stoney cloud expects you to install binary packages, which can be seen with '''[binary R ]''' output.
emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[binary R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 5,295 kB

Total: 1 package (1 reinstall, 1 binary), Size of downloads: 5,295 kB

Would you like to merge these packages? [Yes/No] no

Quitting.
</pre>

=== Force Non-Binary Package ===
If you force a non-binary package, the output will be in the form of '''[ebuild R ]'''.
FEATURES="-getbinpkg" emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] app-arch/cpio-2.11 USE="nls" 995 kB
[ebuild R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 4,523 kB

Total: 2 packages (1 new, 1 reinstall), Size of downloads: 5,518 kB

Would you like to merge these packages? [Yes/No]
</pre>

=== No Binary Package Exists ===
The following example shows you a package with no existing binary package, therefore the package must be compiled on the fly, shown with '''[ebuild N ]'''.
emerge -va htop

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] sys-process/htop-1.0.2 USE="unicode -openvz -vserver" 380 kB

Total: 1 package (1 new), Size of downloads: 380 kB

Would you like to merge these packages? [Yes/No]
</pre>

== Multi-Node Installation ==
Follow the [[Multi-Node_Installation#Specialized_Installation | Specialized Installation]] Guide.

== Basic Testing Steps ==
Get your stoney cloud image:
<source lang='bash'>
version=1.2.10.7 # stoney cloud version

cd /var/virtualization/iso-choosable/
wget http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/iso/foss-cloud-installer-${version}.iso
chown apache:vm-storage foss-cloud-installer-${version}.iso
chmod 644 foss-cloud-installer-${version}.iso
</source>

Get the [http://www.sysresccd.org/SystemRescueCd_Homepage SystemRescueCd] ISO:
<source lang='bash'>
version=4.5.1 # SystemRescueCd version

cd /var/virtualization/iso-choosable/

wget http://sourceforge.net/projects/systemrescuecd/files/sysresccd-x86/${version}/systemrescuecd-x86-${version}.iso

chown apache:vm-storage systemrescuecd-x86-${version}.iso
chmod 644 systemrescuecd-x86-${version}.iso
</source>

Get a Fedora ISO image:
<source lang='bash'>
version=21 # Fedora version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/fedora/linux/releases/${version}/Server/x86_64/iso/Fedora-Server-netinst-x86_64-${version}.iso
chown apache:vm-storage Fedora-Server-netinst-x86_64-${version}.iso
chmod 644 Fedora-Server-netinst-x86_64-${version}.iso
</source>

Lernstick (Test):
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://www.imedias.ch/dateien/lernstick-testversion/lernstick_debian7_2013-12-12.iso
chown apache:vm-storage lernstick_debian7_2013-12-12.iso
chmod 644 lernstick_debian7_2013-12-12.iso
</source>

Get your debian image:
<source lang='bash'>
version=7.8.0 # Debian version

cd /var/virtualization/iso-choosable/
wget http://cdimage.debian.org/debian-cd/${version}/amd64/iso-cd/debian-${version}-amd64-netinst.iso
chown apache:vm-storage debian-${version}-amd64-netinst.iso
chmod 644 debian-${version}-amd64-netinst.iso
</source>

Get your ubuntu desktop image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-desktop-amd64.iso
chown apache:vm-storage ubuntu-${version}-desktop-amd64.iso
chmod 644 ubuntu-${version}-desktop-amd64.iso
</source>

Get your ubuntu server image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-server-amd64.iso
chown apache:vm-storage ubuntu-${version}-server-amd64.iso
chmod 644 ubuntu-${version}-server-amd64.iso
</source>

Get a Windows 2012 Server R2 ISO image:
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://care.dlservice.microsoft.com/dl/download/6/2/A/62A76ABB-9990-4EFC-A4FE-C7D698DAEB96/9600.17050.WINBLUE_REFRESH.140317-1640_X64FRE_SERVER_EVAL_EN-US-IR3_SSS_X64FREE_EN-US_DV9.ISO -O windows_server_2012_r2_64bit_en.iso
chown apache:vm-storage windows_server_2012_r2_64bit_en.iso
chmod 644 windows_server_2012_r2_64bit_en.iso
</source>

If you need the newest Windows Drivers ISO image, visit http://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/bin/

Set three network ranges under https://192.168.140.10/vm-manager/subnet/index.html
192.168.140.64
26
Template Range
template

192.168.140.128
26
Persistent Range
persistent

192.168.140.192
26
Dynamic Range
dynamic

Add the three newly creates network ranges to the VM-Pools under https://192.168.140.10/vm-manager/vmPool/index.html

Create a Virtual Machine Profile under https://192.168.140.10/vm-manager/vmProfile/create.html

Create a Virtual Machine Template under https://192.168.140.10/vm-manager/vmTemplate/create.html and install a basic operating system.

Create a persistent Virtual Machine from the newly created Virtual Machine Template.

== Known Issues ==
None.

[[Category:Installation]]
[[Category:stoney cloud]]

Talk:stoney core: REST API

2015-01-08T15:20:22Z

Chrigu: /* Fragen / Inkonsistenzen */

= Fragen / Inkonsistenzen =

* Wir haben im Header eine Location. Im Body manchmal ja, manchmal nein.
** Gehört die Location in die Body Response rein? Falls ja:
*** Location müsste bei Update auch nicht hochgeschrieben werden?
*** es kommt drauf an: bei einer Collection/Such-Resultat/Liste sollte bei jedem einzelnen Element eine Location mitgegeben werden unter welchem das (vollständige) Element abgerufen werden kann. Als Teil eines Elements macht es meistens keinen Sinn. Im Header sollte es nur als Antwort vom Server kommen bei einem POST-Request (also beim Erstellen einer neuen Ressource) zusammen mit einem 201, siehe [http://en.wikipedia.org/wiki/HTTP_location Wikipedia] --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
**** ACK --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:18, 8 January 2015 (CET)

* Update
** Statt leerem Body wäre hier eine Antwort logisch, wie bei der Kreierung.
*** Die Antwort ist gemäss REST mit dem Code 200 bereits gegeben. Vielleicht auch hier 204 verwenden stattdessen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
**** Ja, strikt gsehen müsste hier 204 zurückkommen. Inhalt brauch es meinern Meinung nach nicht, beim Update ist ja die Location und Id, im gegensatzt zu Create, bereits bekannt. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:18, 8 January 2015 (CET)

* http://wiki.stoney-cloud.org/wiki/stoney_core:_People_Resource_-_REST_API#People_collection_retrieval_response_message
** Location ist definiert, jedoch im Example nicht drin und entsprechend auch nicht umgesetzt.
** Location würde in diesem Falle dem "current" entsprechen (zwischen "pre" und "next").
** Gemäss HTTP Protokoll auch nicht vorgesehen. Fehler in der Definition --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* Caching Controls: Manchmal kommt "Cache-Control: no-cache" zurück, manchmal "Cache-Control: none, private".
** ich vermute dass hier der Webserver noch was selbst macht --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* the service must recognize ETag, Last-Modified and Cache-Control: none provided by the client and act accordingly.
** Machen wir überhaupt etwas mit dem "Cache-Control: none"? Müsste dies nicht eh der Default-Wert sein?

* Mit belongsToResellerId und belongsToCustomerId sind wir inkonsequent. Manchmal haben wir eine belongsToResellerId, manchmal nicht.

* Relations (queries/scoping): Haben wir nicht getestet!
** /v1/resellers/4000001/customers -> collection resource (all customers of reseller with uid=4000001)
** /v1/resellers/4000001/customers/4000002 -> resource (the customer with uid=4000002 of reseller with uid=4000001)
** /v1/customers?belongsToResellerUID=4000001 -> collection resource (all customers of reseller with uid=4000001)
** /v1/customers/4000002 -> resource (the customer with uid=4000002 of reseller with uid=4000001)

* Wollen wir zukünftig statt zuwenig Berechtigungen immer einen leeren JSON Wert zurück geben? Ähnlich wie bei der Suche, wenn sie keine Ergebnisse findet.
** Sonst konkret definieren, was zurück kommen muss.
** Bei einer Collection: ja. (tun wir das nicht bereits?). Bei einem Element muss ein Fehlerwert zurückgegeben werden. Ich hätte hier gerne jedoch 404 Not Found anstatt Permission Denied. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
** Das ist bereits definiert [[stoney_core:_REST_API#Error_codes_and_responses|403 (Forbidden) mit einem JSON error object]] welches weitere Details liefert. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:10, 8 January 2015 (CET)

* Meiner Meinung nach müsste gemäss Spezifikation (On success (200) an empty response message body will be returned, otherwise ...) bei einer Löschung ein leerer JSON String und nicht "{ "success": 1 } zurück gegeben werden.
** http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success
** Wir müssten eigentlich "204 No Content" erhalten:
*** The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request.
** Bei "200 OK" käme sonst "In a POST request the response will contain an entity describing or containing the result of the action." zurück.
*** In diesem Falle würde ich eher "{ "Deletion successful": 1 } erwarten.
** Gemäss [http://stackoverflow.com/questions/2342579/http-status-code-for-update-and-delete Stackoverflow] ist sowohl 200 als 204 ok. Wir haben uns scheinbar für 200 entschieden. Ein Client wird vermutlich nur auf 200/204 prüfen und den Body sowieso ignorieren, von daher egal. Ich persönlich würde 204 nehmen damit wir keinen Text zurückgeben müssen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
*** ACK --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:20, 8 January 2015 (CET)
** Müssten wir nicht auch noch unterschiedliche Response Header zurückgeben? Wenn kein Body, benötige ich auch den Content-Header nicht ... Oder geht das zu weit?

* Actions
** Den neuen HTTP Status Code "202 Accepted" einführen?
*** The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
*** Eine Location für die Status-Abfrage ist nötig! In Form einer Job-ID oder ähnlichem.
*** Ja, aber dafür benötigen wir das Framework dahinter. Im Moment würde ich das ignorieren und so tun als wäre die Aktion sofort und erfolgreich ausgeführt worden. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
**** Finde ich gefährlich, der Client macht weiter obschon es das Objekt noch gar nicht gibt/geben wird (im Fehlerfall) --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:20, 8 January 2015 (CET)
**** die Alternative dazu ist dass wir uns bald für eine Messaging Middleware Lösung für Puppet/MCollective entscheiden und darauf aufbauend einen Job Server hochbringen. Das hiesse vermutlich: [http://www.rabbitmq.com/ RabbitMQ]/[https://github.com/videlalvaro/RabbitMqBundle RabbitMQ Symfony Bundle] und [http://www.celeryproject.org/ Celery] --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 18:03, 7 January 2015 (CET)

* Passwörter
** Bei Update (PUT) haben wir nirgendwo klar definiert, dass das Passwort nicht nötig ist.
** Es ist nirgendwo definiert, wie ein Passwort aussehen darf:
*** Minimale Länge?
*** Gross-/Kleinschreibung?
*** Sonderzeichen und/oder Zahlen?
** Fände es gut, wenn wir dies zentral vorgeben.
*** Wir können minimale Vorgaben dokumentieren, hängt aber ggf vom Authentication Backend ab. Allzuviel Zeit würde hier nicht investieren. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
** Eventuell lassen wir die Vorgaben via API abfragen? In diesem Falle müsste es ins stoney-core Modul gehören?
*** Zu aufwändig für den Nutzen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

Talk:stoney core: REST API

2015-01-08T15:18:29Z

Chrigu: /* Fragen / Inkonsistenzen */

= Fragen / Inkonsistenzen =

* Wir haben im Header eine Location. Im Body manchmal ja, manchmal nein.
** Gehört die Location in die Body Response rein? Falls ja:
*** Location müsste bei Update auch nicht hochgeschrieben werden?
*** es kommt drauf an: bei einer Collection/Such-Resultat/Liste sollte bei jedem einzelnen Element eine Location mitgegeben werden unter welchem das (vollständige) Element abgerufen werden kann. Als Teil eines Elements macht es meistens keinen Sinn. Im Header sollte es nur als Antwort vom Server kommen bei einem POST-Request (also beim Erstellen einer neuen Ressource) zusammen mit einem 201, siehe [http://en.wikipedia.org/wiki/HTTP_location Wikipedia] --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
**** ACK --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:18, 8 January 2015 (CET)

* Update
** Statt leerem Body wäre hier eine Antwort logisch, wie bei der Kreierung.
*** Die Antwort ist gemäss REST mit dem Code 200 bereits gegeben. Vielleicht auch hier 204 verwenden stattdessen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
**** Ja, strikt gsehen müsste hier 204 zurückkommen. Inhalt brauch es meinern Meinung nach nicht, beim Update ist ja die Location und Id, im gegensatzt zu Create, bereits bekannt. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:18, 8 January 2015 (CET)

* http://wiki.stoney-cloud.org/wiki/stoney_core:_People_Resource_-_REST_API#People_collection_retrieval_response_message
** Location ist definiert, jedoch im Example nicht drin und entsprechend auch nicht umgesetzt.
** Location würde in diesem Falle dem "current" entsprechen (zwischen "pre" und "next").
** Gemäss HTTP Protokoll auch nicht vorgesehen. Fehler in der Definition --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* Caching Controls: Manchmal kommt "Cache-Control: no-cache" zurück, manchmal "Cache-Control: none, private".
** ich vermute dass hier der Webserver noch was selbst macht --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* the service must recognize ETag, Last-Modified and Cache-Control: none provided by the client and act accordingly.
** Machen wir überhaupt etwas mit dem "Cache-Control: none"? Müsste dies nicht eh der Default-Wert sein?

* Mit belongsToResellerId und belongsToCustomerId sind wir inkonsequent. Manchmal haben wir eine belongsToResellerId, manchmal nicht.

* Relations (queries/scoping): Haben wir nicht getestet!
** /v1/resellers/4000001/customers -> collection resource (all customers of reseller with uid=4000001)
** /v1/resellers/4000001/customers/4000002 -> resource (the customer with uid=4000002 of reseller with uid=4000001)
** /v1/customers?belongsToResellerUID=4000001 -> collection resource (all customers of reseller with uid=4000001)
** /v1/customers/4000002 -> resource (the customer with uid=4000002 of reseller with uid=4000001)

* Wollen wir zukünftig statt zuwenig Berechtigungen immer einen leeren JSON Wert zurück geben? Ähnlich wie bei der Suche, wenn sie keine Ergebnisse findet.
** Sonst konkret definieren, was zurück kommen muss.
** Bei einer Collection: ja. (tun wir das nicht bereits?). Bei einem Element muss ein Fehlerwert zurückgegeben werden. Ich hätte hier gerne jedoch 404 Not Found anstatt Permission Denied. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
** Das ist bereits definiert [[stoney_core:_REST_API#Error_codes_and_responses|403 (Forbidden) mit einem JSON error object]] welches weitere Details liefert. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:10, 8 January 2015 (CET)

* Meiner Meinung nach müsste gemäss Spezifikation (On success (200) an empty response message body will be returned, otherwise ...) bei einer Löschung ein leerer JSON String und nicht "{ "success": 1 } zurück gegeben werden.
** http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success
** Wir müssten eigentlich "204 No Content" erhalten:
*** The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request.
** Bei "200 OK" käme sonst "In a POST request the response will contain an entity describing or containing the result of the action." zurück.
*** In diesem Falle würde ich eher "{ "Deletion successful": 1 } erwarten.
** Gemäss [http://stackoverflow.com/questions/2342579/http-status-code-for-update-and-delete Stackoverflow] ist sowohl 200 als 204 ok. Wir haben uns scheinbar für 200 entschieden. Ein Client wird vermutlich nur auf 200/204 prüfen und den Body sowieso ignorieren, von daher egal. Ich persönlich würde 204 nehmen damit wir keinen Text zurückgeben müssen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
** Müssten wir nicht auch noch unterschiedliche Response Header zurückgeben? Wenn kein Body, benötige ich auch den Content-Header nicht ... Oder geht das zu weit?

* Actions
** Den neuen HTTP Status Code "202 Accepted" einführen?
*** The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
*** Eine Location für die Status-Abfrage ist nötig! In Form einer Job-ID oder ähnlichem.
*** Ja, aber dafür benötigen wir das Framework dahinter. Im Moment würde ich das ignorieren und so tun als wäre die Aktion sofort und erfolgreich ausgeführt worden. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
**** die Alternative dazu ist dass wir uns bald für eine Messaging Middleware Lösung für Puppet/MCollective entscheiden und darauf aufbauend einen Job Server hochbringen. Das hiesse vermutlich: [http://www.rabbitmq.com/ RabbitMQ]/[https://github.com/videlalvaro/RabbitMqBundle RabbitMQ Symfony Bundle] und [http://www.celeryproject.org/ Celery] --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 18:03, 7 January 2015 (CET)

* Passwörter
** Bei Update (PUT) haben wir nirgendwo klar definiert, dass das Passwort nicht nötig ist.
** Es ist nirgendwo definiert, wie ein Passwort aussehen darf:
*** Minimale Länge?
*** Gross-/Kleinschreibung?
*** Sonderzeichen und/oder Zahlen?
** Fände es gut, wenn wir dies zentral vorgeben.
*** Wir können minimale Vorgaben dokumentieren, hängt aber ggf vom Authentication Backend ab. Allzuviel Zeit würde hier nicht investieren. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
** Eventuell lassen wir die Vorgaben via API abfragen? In diesem Falle müsste es ins stoney-core Modul gehören?
*** Zu aufwändig für den Nutzen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

Talk:stoney core: REST API

2015-01-08T15:10:34Z

Chrigu:

= Fragen / Inkonsistenzen =

* Wir haben im Header eine Location. Im Body manchmal ja, manchmal nein.
** Gehört die Location in die Body Response rein? Falls ja:
*** Location müsste bei Update auch nicht hochgeschrieben werden?
*** es kommt drauf an: bei einer Collection/Such-Resultat/Liste sollte bei jedem einzelnen Element eine Location mitgegeben werden unter welchem das (vollständige) Element abgerufen werden kann. Als Teil eines Elements macht es meistens keinen Sinn. Im Header sollte es nur als Antwort vom Server kommen bei einem POST-Request (also beim Erstellen einer neuen Ressource) zusammen mit einem 201, siehe [http://en.wikipedia.org/wiki/HTTP_location Wikipedia] --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* Update
** Statt leerem Body wäre hier eine Antwort logisch, wie bei der Kreierung.
*** Die Antwort ist gemäss REST mit dem Code 200 bereits gegeben. Vielleicht auch hier 204 verwenden stattdessen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* http://wiki.stoney-cloud.org/wiki/stoney_core:_People_Resource_-_REST_API#People_collection_retrieval_response_message
** Location ist definiert, jedoch im Example nicht drin und entsprechend auch nicht umgesetzt.
** Location würde in diesem Falle dem "current" entsprechen (zwischen "pre" und "next").
** Gemäss HTTP Protokoll auch nicht vorgesehen. Fehler in der Definition --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* Caching Controls: Manchmal kommt "Cache-Control: no-cache" zurück, manchmal "Cache-Control: none, private".
** ich vermute dass hier der Webserver noch was selbst macht --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* the service must recognize ETag, Last-Modified and Cache-Control: none provided by the client and act accordingly.
** Machen wir überhaupt etwas mit dem "Cache-Control: none"? Müsste dies nicht eh der Default-Wert sein?

* Mit belongsToResellerId und belongsToCustomerId sind wir inkonsequent. Manchmal haben wir eine belongsToResellerId, manchmal nicht.

* Relations (queries/scoping): Haben wir nicht getestet!
** /v1/resellers/4000001/customers -> collection resource (all customers of reseller with uid=4000001)
** /v1/resellers/4000001/customers/4000002 -> resource (the customer with uid=4000002 of reseller with uid=4000001)
** /v1/customers?belongsToResellerUID=4000001 -> collection resource (all customers of reseller with uid=4000001)
** /v1/customers/4000002 -> resource (the customer with uid=4000002 of reseller with uid=4000001)

* Wollen wir zukünftig statt zuwenig Berechtigungen immer einen leeren JSON Wert zurück geben? Ähnlich wie bei der Suche, wenn sie keine Ergebnisse findet.
** Sonst konkret definieren, was zurück kommen muss.
** Bei einer Collection: ja. (tun wir das nicht bereits?). Bei einem Element muss ein Fehlerwert zurückgegeben werden. Ich hätte hier gerne jedoch 404 Not Found anstatt Permission Denied. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
** Das ist bereits definiert [[stoney_core:_REST_API#Error_codes_and_responses|403 (Forbidden) mit einem JSON error object]] welches weitere Details liefert. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 16:10, 8 January 2015 (CET)

* Meiner Meinung nach müsste gemäss Spezifikation (On success (200) an empty response message body will be returned, otherwise ...) bei einer Löschung ein leerer JSON String und nicht "{ "success": 1 } zurück gegeben werden.
** http://en.wikipedia.org/wiki/List_of_HTTP_status_codes#2xx_Success
** Wir müssten eigentlich "204 No Content" erhalten:
*** The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request.
** Bei "200 OK" käme sonst "In a POST request the response will contain an entity describing or containing the result of the action." zurück.
*** In diesem Falle würde ich eher "{ "Deletion successful": 1 } erwarten.
** Gemäss [http://stackoverflow.com/questions/2342579/http-status-code-for-update-and-delete Stackoverflow] ist sowohl 200 als 204 ok. Wir haben uns scheinbar für 200 entschieden. Ein Client wird vermutlich nur auf 200/204 prüfen und den Body sowieso ignorieren, von daher egal. Ich persönlich würde 204 nehmen damit wir keinen Text zurückgeben müssen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

* Actions
** Den neuen HTTP Status Code "202 Accepted" einführen?
*** The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place.
*** Eine Location für die Status-Abfrage ist nötig! In Form einer Job-ID oder ähnlichem.
*** Ja, aber dafür benötigen wir das Framework dahinter. Im Moment würde ich das ignorieren und so tun als wäre die Aktion sofort und erfolgreich ausgeführt worden. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
**** die Alternative dazu ist dass wir uns bald für eine Messaging Middleware Lösung für Puppet/MCollective entscheiden und darauf aufbauend einen Job Server hochbringen. Das hiesse vermutlich: [http://www.rabbitmq.com/ RabbitMQ]/[https://github.com/videlalvaro/RabbitMqBundle RabbitMQ Symfony Bundle] und [http://www.celeryproject.org/ Celery] --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 18:03, 7 January 2015 (CET)

* Passwörter
** Bei Update (PUT) haben wir nirgendwo klar definiert, dass das Passwort nicht nötig ist.
** Es ist nirgendwo definiert, wie ein Passwort aussehen darf:
*** Minimale Länge?
*** Gross-/Kleinschreibung?
*** Sonderzeichen und/oder Zahlen?
** Fände es gut, wenn wir dies zentral vorgeben.
*** Wir können minimale Vorgaben dokumentieren, hängt aber ggf vom Authentication Backend ab. Allzuviel Zeit würde hier nicht investieren. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)
** Eventuell lassen wir die Vorgaben via API abfragen? In diesem Falle müsste es ins stoney-core Modul gehören?
*** Zu aufwändig für den Nutzen. --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 12:37, 5 January 2015 (CET)

stoney mail: Pre-sales costumer qualification check list

2015-01-05T13:00:32Z

Chrigu: Chrigu moved page stoney mail: Pre-sales costumer qualification check list to stoney mail: Pre-sales customer qualification check list: corrected typo within title

#REDIRECT [[stoney mail: Pre-sales customer qualification check list]]

stoney mail: Pre-sales customer qualification check list

2015-01-05T13:00:31Z

Chrigu: Chrigu moved page stoney mail: Pre-sales costumer qualification check list to stoney mail: Pre-sales customer qualification check list: corrected typo within title

= Overview =
We need a presales costumer qualification check list, which gathers all the necessary information to be able to provision an new mail domain for a customer of a reseller.

= Checklist =
== Reseller ==
<pre>
Organisation: <ORGANISATION> stepping stone GmbH
Contact Gender: <GENDER> m
Contact: <NAME> <SURNAME> Michael Eichenberger
Address: <ADDRESS> Neufeldstrasse 9
<COUNTRY>-<ZIP> <LOCATION> CH-3012 Bern
Mail: <MAIL> info@stepping-stone.ch
Telephone[1]: <TELEPHONE> +41 31 332 53 63
Mobile[1]: <MOBILE> +41 76 392 36 23
Language: <LANGUAGE> en-GB
</pre>
[1]: Either telephone or mobile need to be present. Both numbers can exist together.

<pre>
Groupware URL: <GROUPWAREURL> groupware.stepping-stone.ch
Logout Redirect URL: <LOGOUTREDIRECTURL> www.stepping-stone.ch
</pre>

== Customer ==
<pre>
Organisation: <ORGANISATION> stepping stone GmbH
Contact Gender: <GENDER> m
Contact: <NAME> <SURNAME> Michael Eichenberger
Address: <ADDRESS> Neufeldstrasse 9
<COUNTRY>-<ZIP> <LOCATION> CH-3012 Bern
Mail: <MAIL> info@stepping-stone.ch
Telephone[1]: <TELEPHONE> +41 31 332 53 63
Mobile[1]: <MOBILE> +41 76 392 36 23
Language: <LANGUAGE> en-GB
</pre>
[1]: Either telephone or mobile need to be present. Both numbers can exist together.

== Mail Domain ==
Values needed for the set-up of a new Mail Domain:
<pre>
Mail Domain Name: <MAILDOMAIN> example.com
Mail Domain Alias Name(s): <MAILDOMAINALIAS> example.org (optional)
</pre>

Some default setting valid for this domain.
<pre>
Default Language: <LANGUAGE> de-CH, de-DE, en-GB, en-US, fr-CH, fr-FR (more languages can be added when needed)
Default Mailbox Size: <MAILBOXSIZE> 100 Megabyte (in 100 Megabyte steps)
Default with Groupware: <GROUPWARE> yes or no, web mail access is always included
</pre>

If you would like to use our Domain Name Servers:
<pre>
Domain Name Server 1: <DNS1> ns-01.stepping-stone.ch
Domain Name Server 2: <DNS2> ns-02.stepping-stone.ch
</pre>

If you want to use your own Domain Name Servers, the entries must look as follows:
<pre>
example.com. 14400 IN MX 10 mail.stepping-stone.ch.
example.com. 14400 IN MX 20 mx-backup.stepping-stone.ch.
</pre>

== Mail Account ==
=== Manual Provisioning of a single Mail Account ===
<pre>
Contact Gender: <GENDER> m
Contact: <NAME> <SURNAME> Michael Eichenberger
Language: <LANGUAGE> en-GB
Mail: <MAIL> michael.eichenberger@stepping-stone.ch
Alias: <ALIAS> mei@stepping-stone.ch (optional, a semicolon separated list)
Password: <PASSWORD> verysecret (may be left free, in this case one will automatically be created for you)
Quota: <QUOTA> 100 Megabyte (in 100 Megabyte steps)
Groupware: <GROUPWARE> yes (yes or no, web mail access is always included)
Forwards: <FORWARDS> - (optional, a semicolon separated list)
</pre>

=== Bulk load with CSV file ===
A CSV file in the following structure can be provided for multiple Mail Accounts:

{| class="wikitable sortable" style="width: 100%;"
|-
!Name 
!Surname 
!Gender [f,m,n]
!Language [de-CH, de-DE, en-GB, en-US, fr-CH, fr-FR] x1
!Mail 
!Alias (semicolon separated)
!Password (will be generated if empty)
!Quota (in 100 Megabyte steps) x1
!Groupware [yes,no] x1
!Forwards (semicolon separated)

|-
|Michael
|Eichenberger
|m
|en-GB
|michael.eichenberger@stepping-stone.ch
|mei@stepping-stone.ch
|
|100
|yes
|support@stepping-stone.ch;info@stepping-stone.ch

|-
|Info
|stepping stone GmbH
|n
|de-CH
|info@stepping-stone.ch
|support@stepping-stone.ch;hosting@stepping-stonec.ch
|secret45
|300
|yes
|

|-
|}

* x1: If the default values (Language, Mailbox Size and Groupware) are set, these columns can be left empty.

The above table leads to the following CSV file:
<pre>
Michael,Eichenberger,m,en-GB,michael.eichenberger@stepping-stone.ch,mei@stepping-stone.ch,,100,yes,michael.eichenberger@gmail.com
Info,stepping stone GmbH,n,de-CH,info@stepping-stone.ch,support@stepping-stone.ch;hosting@stepping-stonec.ch,secret45,300,yes,
</pre>

=== Provisioning via REST API ===
You can also use the [[stoney core: People Resource - REST API]] and the [[stoney mail: Mail Resource - REST API]] to provision a person and the the mail accounts.

[[Category:stoney mail]]

stoney cloud: Upgrade

2014-11-11T12:19:33Z

Chrigu: /* Updating from 1.2.10.7 or earlier to 1.2.10.8_rc4 or newer */

= Overview =
This guide explains, what you need to do during the installation of your Multi-Node Installation.

== Prepare your stoney cloud installation for the update ==

=== <= 1.2.10.3 ===

If you have a '''productive''' (releases) stoney cloud Installation, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/releases/1.2/packages"' >> /etc/portage/make.conf
</source>

If you have a '''test''' (pre-releases) stoney cloud Installation instead, execute the following command:
<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf
</source>

'''IMPORTANT:''' Even a pre-release ISO may result in a stable installation, depending on when it was generated in the release cycle. Please verify by executing <code>git branch</code> in <code>/usr/portage</code> and <code>/var/lib/layman/foss-cloud</code> whether this is the case, and [[stoney_cloud:_Switch_to_testing_branch|switch to the testing branch]] if needed (that is: if the branch displayed does not contain the words <code>pre</code> or <code>testing</code>. If the branch is empty, that means you have a brand new installation without anything yet. In that case, directly check the configuration files <code>/usr/portage/.git/config</code> and/or <code>/var/lib/layman/foss-cloud/.git/config</code> to see which branch it would check out upon <code>emerge --sync</code> and from where.).

=== >= 1.2.10.4 ===

Execute the following command to register the binary package mirror (since for now there will be only pre-releases, but with better quality than FOSS-Cloud releases):

<source lang="bash">
echo 'PORTAGE_BINHOST="http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/packages"' >> /etc/portage/make.conf

# Disable the SYNC from rsync since newer portage versions otherwise won't accept a portage tree via git
sed -i -e 's|^SYNC|#SYNC|' /etc/portage/make.conf
</source>

== Update ==

=== Updating from 1.2.10.7 or earlier to 1.2.10.8_rc4 or newer ===

A complete rebuild of all packages was required, therefore the update guide is different:

<source lang='bash'>
emerge --sync

emerge -eK world -va

# sst-libvirt-hooks is not part of the stoney-cloud anymore since it requires further configuration
# make sure that it still gets updated and not removed later, if you have it installed and enabled
emerge -K app-emulation/sst-libvirt-hooks

dispatch-conf

# Switch runtime switchable options
eselect python set python3.3
eselect php set cli php5.5
eselect php set apache2 php5.5
gcc-config x86_64-pc-linux-gnu-4.7.3
</source>

During the dispatch-conf the following may appear:
* /etc/libvirt/libvirt.conf: you may get the suggestion to remove almost all content. Quit dispatch-conf and do: <code>rm /etc/libvirt/._mrg*</code> and start dispatch-conf again.
* /etc/libvirt/libvirt.conf: merge all whitespace/comment changes but make sure you don't overwrite the <code>listen_addr</code>
* /etc/portage/make.conf: merge all changes beside the <code>PORTAGE_BINHOST</code>
* /var/www/localhost/htdocs/vm-manager/vm_config.php: merge the versions, newly added lines and comments. Avoid changes on sstSourceHostName array

To make sure everything works, reboot and then cleanup:

<source lang='bash'>
emerge --depclean -va
</source>

* If the cleanup fails stating that <code>Locale-gettext</code> and <code>dev-libs/boost</code> depends on some version of perl, reinstall that package manually once and try again:
<source lang='bash'>
emerge -1Kva dev-libs/boost Locale-gettext

# same for autoconf-/automake-wrapper if host was used to build stuff:
emerge -1K sys-devel/autoconf-wrapper sys-devel/automake-wrapper
</source>
* '''WARNING''': this also removes the current kernel. If you want to play it safe, reboot first, then depclean, then reboot again
* Rebuilde separately installed perl modules and remove traces of the old perl version:
<source lang='bash'>
perl-cleaner --all -- -va
rm -rf /usr/lib64/perl5/{vendor_perl,}/5.12.4
</source>

=== Regular Update ===

Makes sure, your local portage tree is updated:
emerge --sync

Now you can make sure, that you've got the current stoney cloud version installed:
emerge -KuDva virtual/foss-cloud

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!

Total: 0 packages, Size of downloads: 0 kB

* virtual/foss-cloud-1.2.10.4

Would you like to add these packages to your world favorites? [Yes/No] '''no'''
</pre>

If you have updated you stoney cloud, you might want to sanely update your configuration files after emerging new packages (including updates):
dispatch-conf

== Installing Software Examples ==
Per default, the stoney cloud expects you to install binary packages. So if you don't pass any special parameters to the emerge command, the binary package (if it exists) will be used.

=== Binary Package ===
Per default, the stoney cloud expects you to install binary packages, which can be seen with '''[binary R ]''' output.
emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[binary R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 5,295 kB

Total: 1 package (1 reinstall, 1 binary), Size of downloads: 5,295 kB

Would you like to merge these packages? [Yes/No] no

Quitting.
</pre>

=== Force Non-Binary Package ===
If you force a non-binary package, the output will be in the form of '''[ebuild R ]'''.
FEATURES="-getbinpkg" emerge -va git

<pre>
These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] app-arch/cpio-2.11 USE="nls" 995 kB
[ebuild R ] dev-vcs/git-1.7.12.4 USE="blksha1 curl iconv nls pcre perl threads webdav -cgi -cvs -doc -emacs -gpg -gtk -highlight (-ppcsha1) -python -subversion {-test} -tk -xinetd" 4,523 kB

Total: 2 packages (1 new, 1 reinstall), Size of downloads: 5,518 kB

Would you like to merge these packages? [Yes/No]
</pre>

=== No Binary Package Exists ===
The following example shows you a package with no existing binary package, therefore the package must be compiled on the fly, shown with '''[ebuild N ]'''.
emerge -va htop

<pre>
Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies... done!
[ebuild N ] sys-process/htop-1.0.2 USE="unicode -openvz -vserver" 380 kB

Total: 1 package (1 new), Size of downloads: 380 kB

Would you like to merge these packages? [Yes/No]
</pre>

== Multi-Node Installation ==
Follow the [[Multi-Node_Installation#Specialized_Installation | Specialized Installation]] Guide.

== Basic Testing Steps ==
Get your stoney cloud image:
<source lang='bash'>
version=1.2.10.7 # stoney cloud version

cd /var/virtualization/iso-choosable/
wget http://packages.stoney-cloud.org/stoney-cloud/pre-releases/1.2/iso/foss-cloud-installer-${version}.iso
chown apache:vm-storage foss-cloud-installer-${version}.iso
chmod 644 foss-cloud-installer-${version}.iso
</source>

Get a Fedora ISO image:
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://download.fedoraproject.org/pub/fedora/linux/releases/20/Fedora/x86_64/iso/Fedora-20-x86_64-netinst.iso
chown apache:vm-storage Fedora-20-x86_64-netinst.iso
chmod 644 Fedora-20-x86_64-netinst.iso
</source>

Lernstick (Test):
<source lang='bash'>
cd /var/virtualization/iso-choosable/
wget http://www.imedias.ch/dateien/lernstick-testversion/lernstick_debian7_2013-12-12.iso
chown apache:vm-storage lernstick_debian7_2013-12-12.iso
chmod 644 lernstick_debian7_2013-12-12.iso
</source>

Get your debian image:
<source lang='bash'>
version=7.4.0 # debian version

cd /var/virtualization/iso-choosable/
wget http://cdimage.debian.org/debian-cd/${version}/amd64/iso-cd/debian-${version}-amd64-netinst.iso
chown apache:vm-storage debian-${version}-amd64-netinst.iso
chmod 644 debian-${version}-amd64-netinst.iso
</source>

Get your ubuntu desktop image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-desktop-amd64.iso
chown apache:vm-storage ubuntu-${version}-desktop-amd64.iso
chmod 644 ubuntu-${version}-desktop-amd64.iso
</source>

Get your ubuntu server image:
<source lang='bash'>
version=14.04 # ubuntu version

cd /var/virtualization/iso-choosable/
wget http://mirror.switch.ch/ftp/mirror/ubuntu-cdimage/${version}/ubuntu-${version}-server-amd64.iso
chown apache:vm-storage ubuntu-${version}-server-amd64.iso
chmod 644 ubuntu-${version}-server-amd64.iso
</source>

Set three network ranges under https://192.168.140.10/vm-manager/subnet/index.html
192.168.140.64
26
Template Range
template

192.168.140.128
26
Persistent Range
persistent

192.168.140.192
26
Dynamic Range
dynamic

Add the three newly creates network ranges to the VM-Pools under https://192.168.140.10/vm-manager/vmPool/index.html

Create a Virtual Machine Profile under https://192.168.140.10/vm-manager/vmProfile/create.html

Create a Virtual Machine Template under https://192.168.140.10/vm-manager/vmTemplate/create.html and install a basic operating system.

Create a persistent Virtual Machine from the newly created Virtual Machine Template.

== Known Issues ==
None.

[[Category:Installation]]
[[Category:stoney cloud]]

stoney core: REST API

2014-08-06T07:29:47Z

Chrigu: /* Input validations */

= Overview =

= Entities, Roles and Relationships =
== Overview ==
Description, how everything works together.Entitlement, Access and Roles

== Entities ==
An Entity is always a company or a person.

=== Service Provider ===
A service provider is the owner of the stoney cloud installation. One or more employees of the the service provider must be [[#Super User | super users]].

=== Reseller(s) ===
A reseller sells services of the service provider as his own. He is responsible for the administration of his customers and their services.

=== Customers(s) ===
A customer subscribes to services that the reseller sells. The customer can administrate his own people, employees and services.

=== People ===
==== Person ====
A person belonging one or more resellers and one or more customers. Normally, a person would belong to one reseller and one customer.

==== Employee ====
A person, which is employed by one or more resellers and/or one or more customers.

==== Super User ====
A super user is a person which has the right to complete the REST API functionality. The stoney cloud is delivered with one active super user. See the [[stoney_core:_OpenLDAP_directory_data_organisation#People_.28Superuser.29 | People (Superuser)]] description in the [[stoney core: OpenLDAP directory data organisation]].

== Roles ==
The roles are not finalized yet.

== Relationships ==
The relationships are hierarchical:

'''Service Provider Person''' > '''Reseller Employee''' > '''Customer Employee''' > '''Reseller Person''' and '''Customer Person'''

The further down you go, the less rights a person has (this is currently independent from any existing roles, as these have not been finalized yet).

=== Service Provider Person (SPP) ===
Definition of a Service Provider Person:
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000002
| Unique id of the person.
|-

| -
| sstBelongsToUID
| 1
| Hidden (internal) attribute, that will lose it's meaning, when the roles are finalized. Makes a person a super user.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000001
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000000
| Shows the reseller (in this case), that the person is an employee of (multiple resellers possible, N:M relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000001
| Shows the customer (in this case), that the person is an employee of (multiple customers possible, N:M relation).
|-

|}

==== Service Provider Person (SPP) Rights ====
A Service Provider Person can just about do anything. The following rights are unique for a Service Provider Person (SPP):
* SPP.00: '''Create a reseller''': Can create a reseller.
* SPP.01: '''Retrieve all resellers''': Can retrieve all resellers.
* SPP.02: '''Retrieve a reseller''': Can retrieve a reseller.
* SPP.03: '''Update a reseller:''' Can update a reseller.
* SPP.04: '''Partly Update a reseller''': Can partly update a reseller.
* SPP.05: '''Delete reseller''': Can delete a reseller (if no customers, people or services are linked to the reseller).
* SPP.06: '''Create a person''': Can create a person (and make them a super user, an employee of one or more reseller(s) and an employee of one or more reseller(s)).
* SPP.07: '''Retrieve all people''': Can retrieve all people.
* SPP.08: '''Retrieve a person''': Can retrieve a person.
* SPP.09: '''Update a person:''' Can update a person (including making them a super user, an employee of one or more reseller(s) and an employee of one or more reseller(s)).
* SPP.10: '''Partly Update a person''': Can partly update a person.
* SPP.11: '''Delete person''': Can delete a person (if no services are linked to the person).

=== Reseller Employee (RE) ===
Definition of a Reseller Employee (RE):
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000003
| Unique id of the person.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000001
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000000
| Shows the reseller (in this case), that the person is an employee of (multiple resellers possible, N:M relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000001
| Shows the customer (in this case), that the person is an employee of (multiple customers possible, N:M relation).
|-

|}

==== Reseller Employee (RE) Rights ====
Sees the reseller they belong to, themselves, their own customers, people and their services. The following rights exist for a Reseller Employee (RE) and a Service Provider Person (SPP):
* RE.00: '''Retrieve some resellers''': Can retrieve the reseller(s) they are an employee of.
* RE.01: '''Retrieve a reseller''': Can retrieve one of the reseller(s) they are an employee of.
* RE.02: '''Update a reseller:''' Can update one of the reseller(s) they are an employee of.
* RE.03: '''Partly Update a reseller''': Can partly update one of the reseller(s) they are an employee of.

* RE.04: '''Create a customer''': Can create a customer.
* RE.05: '''Retrieve all customers''': Can retrieve all their customers.
* RE.06: '''Retrieve a customer''': Can retrieve one of their customers.
* RE.07: '''Update a customer:''' Can update one of their customers.
* RE.08: '''Partly Update a customer''': Can partly update one of their customers.
* RE.09: '''Delete customer''': Can delete one of their customers (if no people or services are linked to the customer).

* RE.10: '''Create a person''': Can create a person (including making them an employee of their reseller(s) and of their customer(s)).
* RE.11: '''Retrieve all people''': Can retrieve all their people (of their reseller(s) and their customer(s)).
* RE.12: '''Retrieve a person''': Can retrieve one of their people (of their reseller(s) and their customer(s)).
* RE.13: '''Update a person:''' Can update a person (including making them an employee of their reseller(s) and of their customer(s)).
* RE.14: '''Partly Update a person''': Can partly update a person.
* RE.15: '''Delete person''': Can delete a person (if no services are linked to the person).

=== Customer Employee (CE) ===
Definition of a Customer Employee (CE):
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000004
| Unique id of the person.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000002
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000002
| Shows the customer (in this case), that the person is an employee of (multiple customers possible, N:M relation).
|-

|}

==== Customer Employee (CE) Rights ====
Sees the customer they belong to, themselves, their own people and their services. The following rights exist for a Customer Employee (CE), a Reseller Employee (RE) and a Service Provider Person (SPP):
* CE.00: '''Retrieve some customers''': Can retrieve the customer(s) they are an employee of.
* CE.01: '''Retrieve a customer''': Can retrieve one of the customer(s) they are an employee of.
* CE.02: '''Update a customer:''' Can update one of the customer(s) they are an employee of.
* CE.03: '''Partly Update a customer''': Can partly update one of the customer(s) they are an employee of.

* CE.04: '''Create a person''': Can create a person (including making them an employee of their customer(s)).
* CE.05: '''Retrieve all people''': Can retrieve all their people (of their customer(s)).
* CE.06: '''Retrieve a person''': Can retrieve one of their people (of their customer(s)).
* CE.07: '''Update a person:''' Can update a person (including making them an employee of their customer(s)).
* CE.08: '''Partly Update a person''': Can partly update a person.
* CE.09: '''Delete person''': Can delete a person (if no services are linked to the person).

=== Reseller Person (P) and Customer Person (P) ===
Definition of a Reseller Person (P) and Customer Person (P):
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000005
| Unique id of the person.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000002
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

|}

==== Reseller Person (P) and Customer Person (P) Rights ====
A Reseller Person (P) and Customer Person (P) act exactly the same. They see themselves and their own services.
Sees the customer they belong to, themselves, their own people and their services. The following rights exist for a Reseller Person (P), a Customer Person (P), a Customer Employee (CE), a Reseller Employee (RE) and a Service Provider Person (SPP):
* P.00: '''Retrieve a person''': Can retrieve themselves.
* P.01: '''Update a person:''' Can update themselves.
* P.02: '''Partly Update a person''': Can partly update themselves.

= REST API documentation =
=== Reserved Keywords ===
We have some special reserved keywords, which can no be used by the REST API:
* sort: Used for sorting.
* q: Full text search.
* page: Pagination.

=== Base URI ===
The RESTful web service has to be accessible via a secure HTTP (HTTPS) base URI, for instance <code>https://api.example.com/v1</code>.
The definition of the base URI is up to the provider of the service. The only requirements are the use of HTTPS and the presence of the service's version information, so that further changes are possible without breaking existing clients.

=== Client authentication and authorization ===
The service needs to authenticate each client via HTTP basic authentication by a user name and a corresponding password. If a unauthenticated client tries to access the service, it will response with a <code>401</code> (Unauthorized) HTTP [[#Error_codes_and_responses|error code]].

Furthermore the service must retrieve the authenticated users role and object ownership and respect their respective value when returning collections and elements and acting on HTTP methods. If a client tries to get, modify or delete an element for which it is not authorized, the services will response with a <code>403</code> (Forbidden) HTTP [[#Error_codes_and_responses|error code]] and includes a descriptive authorization validation message within the JSON error object.

To solely authentication a person, use the resource described under [[stoney core: Authentication Resource - REST API]].

=== Data interchange format ===
The service needs to accept and send all data in the JSON data interchange format via HTTP, encoded as UTF-8. Thus a client needs to accept and use the [http://tools.ietf.org/html/rfc4627 <code>application/json</code>] media type. Further media types might be supported in the future.

This results in the following required request and response headers:
{| class="wikitable sortable"
|-
! Request header
! Response header

|-
|<pre>
Accept: application/json
Accept-Charset: utf-8
</pre>
| <pre>Content-Type: application/json;charset=utf-8</pre>

|}

* If the client sends an <code>Accept</code> header with an unsupported value (at the moment only <code>application/json</code> is supported), the service will respond with a <code>406</code> (Not Acceptable) [[#Error codes and responses|error code]].
* If the client sends an <code>Accept-Charset</code> header with an unsupported value (at the moment only <code>utf-8</code> is supported), the service will respond with a <code>406</code> (Not Acceptable) [[#Error codes and responses|error code]].
* If no <code>Accept</code> header is sent, the server will use JSON, possibly pretty-printed and annotated.
* If no <code>Accept-Charset</code> header is sent, the server send the response with <code>utf-8</code> as charset.
* If the client sends a <code>Content-Type</code> other than <code>application/json</code> on a POST, PUT or PATCH request, the service will respond with a <code>415</code> (Unsupported Media Type) [[#Error codes and responses|error code]].
* If the client sends invalid JSON, the service will response with a <code>400</code> (Bad Request) HTTP [[#Error codes and responses|error code]] and a descriptive error message within the error object.
* When returning a <code>401</code>, a proper <code>WWW-Authenticate</code> header must be sent as well as documented in [http://tools.ietf.org/html/rfc7235#page-7 RFC7235 (or earlier HTTP 1.1/1.0 RFCs)].

Unless otherwise noted, the [http://tools.ietf.org/wg/httpbis/ HTTPbis RFCs] always apply.

Future extension:
Client may supply <code>application/vnd.org.stoney-cloud.api+json</code> as <code>Content-Type</code> to declare the requested schema/format of the data. This can then also be used to introduce additional versioning.

=== Error codes and responses ===
The service returns appropriate HTTP status codes for every request, the following table lists the commonly used codes:

{| class="wikitable sortable"
|-
! HTTP status code
! Text
! Description

|-
| 200
| OK
| Success.

|-
| 201
| Created
| A new resource was successfully created.

|-
| 400
| Bad Request
| The request was invalid. A descriptive error message will be sent within the response body.

|-
| 404
| Not Found
| The requested resource could not be found but may be available again in the future.

|-
| 406
| Not Acceptable
| The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.

|-
| 401
| Unauthorized
| The client has failed or not yet tried to authenticate.

|-
| 403
| Forbidden
| The client is not allowed to access the requested resource.

|-
| 415
| Unsupported Media Type
| The request entity has a media type which the server or resource does not support. For example, sending XML instead of JSON in a POST, PUT or PATCH method.

|-
| 422
| Unprocessable Entity
| The request was well-formed but was unable to be followed due to semantic errors. For example, a client sends a invalid field value (numbers instead of characters) in a JSON object.

|-
| 428
| Precondition Required
| The client did not provide a proper ETag and/or Last-modification header when updating an object via PUT, see http://tools.ietf.org/html/rfc6585#section-3

|-
| 429
| Too Many Requests
| There were too many requests within a given time-period, see http://tools.ietf.org/html/rfc6585#section-4

|-
| 500
| Internal Server Error
| An internal error succoured. A descriptive error message will be sent within the response body.

|-
| 503
| Service Unavailable
| The service is temporary unavailable, because it is overloaded or down for maintenance

|}

Additionally the service returns a descriptive error object in case a HTTP error was returned (4xx) within the message body of the response. An error object consists of an error code and a human readable error message, with further detailed error messages if applicable.

<source lang='javascript'>
{
"error": {
"module": "core",
"code": 123,
"message": "Validation failed"
"details" : [
{
"module": "core",
"code" : 5432,
"field" : "firstName",
"message" : "First name cannot be longer than 35 characters"
},
{
"module": "core",
"code" : 5123,
"field" : "password",
"message" : "Password cannot be blank"
}
]
}
}
</source>

=== Mandatory headers ===

Besides the above mentioned headers, the following headers are mandatory.

* every answer to a GET reqest should always include <code>[http://en.wikipedia.org/wiki/HTTP_ETag ETag]</code> and <code>Last-Modified</code> header. This allows a proxy to cache requests and a client to revalidate already fetched data.
* the service must recognize <code>ETag</code>, <code>Last-Modified</code> and <code>Cache-Control: none</code> provided by the client and act accordingly.
* every answer to a GET request must include proper <code>Cache-Control</code> headers
* every PUT request to update an object must include the <code>ETag</code> provided by the <code>GET</code> request to fetch the object initially. The API must respond with an <code>428 (Precondition Required)</code> if the ETag is missing.

''Implementation notes'':
* one could use the internal LDAP attributes <code>entryCSN</code> and/or <code>modifyTimestamp</code> to generate an ETag via a hash function. In the case of business objects where multiple LDAP objects are aggregated for one exposed object, the hash can be generated over all constituent objects
* the <code>Last-Modified</code> header can be used to directly limit the search results when hitting the LDAP via the <code>modifyTimestamp</code> internal attribute. Ex. <code>modifytimestamp>=20060301000000Z</code>

=== Resources and HTTP methods ===
Resources are always nouns, and specified in plural (such as resellers, customers, users etc.), this prevents one from dealing with irregular pluralizations such as person/people.

The manipulation of resources happens via the HTTP request methods such as <code>GET</Code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code> and <code>PATCH</code>.
The following example illustrates the concept with a fictive user resource:
{| class="wikitable sortable"
|-
! HTTP request
! Description

|-
| <code>GET /users</code>
| Retrieves a list of users

|-
| <code>GET /users/12345678</code>
| Retrieves a specific user with user ID 12345678

|-
| <code>POST /users</code>
| Creates a new user

|-
| <code>PUT /users/12345678</code>
| Updates the user with user ID 12345678

|-
| <code>PATCH /users/12345678</code>
| Partly updates the user with user ID 12345678

|-
| <code>DELETE /users/12345678</code>
| Deletes the user with user ID 12345678

|-
| <code>DELETE /users</code>
| Deletes all users

|}

==== POST ====

On successful creation of an element, the service must return an URI string to the newly created element.

'''Example''':

Request:
<pre>
POST /v1/users/ HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
Content-Type: application/json
</pre>
<source lang='javascript'>
{
"usersName": "Mueller",
"usersType": "reseller",
}
</source>

Answer:
<pre>
HTTP/1.1 201 Created
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
Location: https://api.example.com/v1/users/67890
</pre>
<source lang='javascript'>
{
"id": 67890,
"location": "https://api.example.com/v1/users/67890",
}
</source>

=== Relations ===
Resources which stand in relation with each other are represented as URIs (scoping):
* <code>/v1/resellers/4000001/customers</code> -> collection resource (all customers of reseller with uid=4000001)
* <code>/v1/resellers/4000001/customers/4000002</code> -> resource (the customer with uid=4000002 of reseller with uid=4000001)

The following queries have the same effect as the URIs from above:
* <code>/v1/customers?belongsToResellerUID=4000001</code> -> collection resource (all customers of reseller with uid=4000001)
* <code>/v1/customers/4000002</code> -> resource (the customer with uid=4000002 of reseller with uid=4000001)

Relations are always returned as URIs, which the client can hit.

Future possibilities (sub objects) which aren't currently implemented:
* If a relation can only exist within another resource, it will be represent by its URI, for example: <code>/threads/123/messages/45</code>. This URI represents the message with ID #45 of the forum thread with ID #123.

=== Filtering, sorting and searching ===
Filter, sort and search requests are added as query parameters to the resource URI.

For '''filtering''' the objects returned by a resource URI, the name of an object's attribute is added as a query parameter with the required value. For example, get all active user elements:
GET /v1/users?status=active

For '''sorting''' the objects returned by a resource URI, the query parameter <code>sort</code> is added with the object's sort attribute(s) as the value. The following example will sort users by lastname and firstname in lexicographic ascending order:
GET /v1/users?sort=lastname,firstname

The following will sort users by lastname in lexicographic descending and firstname in lexicographic ascending order:
GET /v1/users?sort=-lastname,firstname

The following will sort users by lastname and by firstname in lexicographic descending order:
GET /v1/users?sort=-lastname,-firstname

For '''full text search''' the objects returned by a resource URI, the query parameter <code>q</code> is added with the value to search for. For example
GET /v1/users?q=Muell
will return users named <code>Mueller</code> as well as the ones living at <code>Muellhaldenstrasse</code>.

For full text search over all the available resources visit [[stoney core: Search Resource - REST API]].

=== Pagination ===
Responses with multiple items will be '''limited and paginated to 30 items''' per default (defined on server-side). Further items can be accessed by appending the <code>page</code> query parameter. The number of items to be returned can be '''raised to a maximum of 100''' (defined on server-side), by specifying the <code>per_page</code> query parameter.

For example, to request page number 3 with 40 items per page, a client would send the following GET request:
<pre>
GET /v1/people?page=3&per_page=40
</pre>

If pagination is requested by the client and/or enforced by the server (e.g. if the number of available records is larger than the default count and no pagination requested), the service returns [http://tools.ietf.org/html/rfc5988#section-6.2.2 official registered link relation types] (<code>next</code>, <code>prev</code>, <code>first</code>, <code>last</code>) within the HTTP [http://tools.ietf.org/html/rfc5988#section-5 Link header field] for pagination use:
<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
Link: <https://api.example.com/v1/resellers?page=1&per_page=30>; rel="first",
<https://api.example.com/v1/resellers?page=2&per_page=30>; rel="prev",
<https://api.example.com/v1/resellers?page=4&per_page=30>; rel="next",
<https://api.example.com/v1/resellers?page=10&per_page=30>; rel="last"
X-Total-Count: 295
</pre>

The client MUST use those pagination links, rather than constructing the URLs by itself.

Furthermore the service sets a custom header <code>X-Total-Count</code> containing the (estimation of) total number of records.

=== Field specifications and limitations ===
@TBD: Do we want a possibility to specify which fields should be return on a GET request? This could either be used to save further requests to element URIs, if one fetches items from a collection URL, or to reduce the required amount of data to be transferred if one only uses a few attributes from a response. If yes, a <code>fields</code> query parameter should be added to a resource which takes a comma separated list of field names, such as <code>https://api.example.com/v1/users?fields=firstname,lastname</code>.

Maybe. In a collection there shouldn't be as many elements returned such that this may be come a problem. On the other hand, if we return large sets, we should rather use caching properly. Making it possible to specify fields makes cachign even harder. See for example https://blog.apigee.com/detail/restful_api_design_can_your_api_give_developers_just_the_information/ --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 11:47, 11 December 2013 (CET)

=== Input validations ===
The service validates all input it receives from a client and returns a <code>422</code> (Unprocessable Entity) HTTP [[#Error_codes_and_responses|status code together with a descriptive error object]] in case of an input violation (but well-formed JSON).

In case a client passes invalid JSON (a JSON parser is unable to parse the JSON string), the service returns a <code>400</code> (Bad Request) HTTP [[#Error_codes_and_responses|status code together with a descriptive error object]] containing the JSON parser error message.

= Notes =
* Resource for modules => which modules are available for a given role and belong to which category
* Nested URLs vs. filter via get parameter => <code>/users/<UID>/products</code> vs. <code>/products/?userId=<UID></code>, (choose a better word for product?)
* Sudo mechanism, via custom HTTP header, for example <code>X-USER</code>

[[Category:REST API]][[Category:stoney core]]

stoney core: REST API

2014-08-06T07:18:52Z

Chrigu: /* Error codes and responses */

= Overview =

= Entities, Roles and Relationships =
== Overview ==
Description, how everything works together.Entitlement, Access and Roles

== Entities ==
An Entity is always a company or a person.

=== Service Provider ===
A service provider is the owner of the stoney cloud installation. One or more employees of the the service provider must be [[#Super User | super users]].

=== Reseller(s) ===
A reseller sells services of the service provider as his own. He is responsible for the administration of his customers and their services.

=== Customers(s) ===
A customer subscribes to services that the reseller sells. The customer can administrate his own people, employees and services.

=== People ===
==== Person ====
A person belonging one or more resellers and one or more customers. Normally, a person would belong to one reseller and one customer.

==== Employee ====
A person, which is employed by one or more resellers and/or one or more customers.

==== Super User ====
A super user is a person which has the right to complete the REST API functionality. The stoney cloud is delivered with one active super user. See the [[stoney_core:_OpenLDAP_directory_data_organisation#People_.28Superuser.29 | People (Superuser)]] description in the [[stoney core: OpenLDAP directory data organisation]].

== Roles ==
The roles are not finalized yet.

== Relationships ==
The relationships are hierarchical:

'''Service Provider Person''' > '''Reseller Employee''' > '''Customer Employee''' > '''Reseller Person''' and '''Customer Person'''

The further down you go, the less rights a person has (this is currently independent from any existing roles, as these have not been finalized yet).

=== Service Provider Person (SPP) ===
Definition of a Service Provider Person:
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000002
| Unique id of the person.
|-

| -
| sstBelongsToUID
| 1
| Hidden (internal) attribute, that will lose it's meaning, when the roles are finalized. Makes a person a super user.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000001
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000000
| Shows the reseller (in this case), that the person is an employee of (multiple resellers possible, N:M relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000001
| Shows the customer (in this case), that the person is an employee of (multiple customers possible, N:M relation).
|-

|}

==== Service Provider Person (SPP) Rights ====
A Service Provider Person can just about do anything. The following rights are unique for a Service Provider Person (SPP):
* SPP.00: '''Create a reseller''': Can create a reseller.
* SPP.01: '''Retrieve all resellers''': Can retrieve all resellers.
* SPP.02: '''Retrieve a reseller''': Can retrieve a reseller.
* SPP.03: '''Update a reseller:''' Can update a reseller.
* SPP.04: '''Partly Update a reseller''': Can partly update a reseller.
* SPP.05: '''Delete reseller''': Can delete a reseller (if no customers, people or services are linked to the reseller).
* SPP.06: '''Create a person''': Can create a person (and make them a super user, an employee of one or more reseller(s) and an employee of one or more reseller(s)).
* SPP.07: '''Retrieve all people''': Can retrieve all people.
* SPP.08: '''Retrieve a person''': Can retrieve a person.
* SPP.09: '''Update a person:''' Can update a person (including making them a super user, an employee of one or more reseller(s) and an employee of one or more reseller(s)).
* SPP.10: '''Partly Update a person''': Can partly update a person.
* SPP.11: '''Delete person''': Can delete a person (if no services are linked to the person).

=== Reseller Employee (RE) ===
Definition of a Reseller Employee (RE):
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000003
| Unique id of the person.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000001
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000000
| Shows the reseller (in this case), that the person is an employee of (multiple resellers possible, N:M relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000001
| Shows the customer (in this case), that the person is an employee of (multiple customers possible, N:M relation).
|-

|}

==== Reseller Employee (RE) Rights ====
Sees the reseller they belong to, themselves, their own customers, people and their services. The following rights exist for a Reseller Employee (RE) and a Service Provider Person (SPP):
* RE.00: '''Retrieve some resellers''': Can retrieve the reseller(s) they are an employee of.
* RE.01: '''Retrieve a reseller''': Can retrieve one of the reseller(s) they are an employee of.
* RE.02: '''Update a reseller:''' Can update one of the reseller(s) they are an employee of.
* RE.03: '''Partly Update a reseller''': Can partly update one of the reseller(s) they are an employee of.

* RE.04: '''Create a customer''': Can create a customer.
* RE.05: '''Retrieve all customers''': Can retrieve all their customers.
* RE.06: '''Retrieve a customer''': Can retrieve one of their customers.
* RE.07: '''Update a customer:''' Can update one of their customers.
* RE.08: '''Partly Update a customer''': Can partly update one of their customers.
* RE.09: '''Delete customer''': Can delete one of their customers (if no people or services are linked to the customer).

* RE.10: '''Create a person''': Can create a person (including making them an employee of their reseller(s) and of their customer(s)).
* RE.11: '''Retrieve all people''': Can retrieve all their people (of their reseller(s) and their customer(s)).
* RE.12: '''Retrieve a person''': Can retrieve one of their people (of their reseller(s) and their customer(s)).
* RE.13: '''Update a person:''' Can update a person (including making them an employee of their reseller(s) and of their customer(s)).
* RE.14: '''Partly Update a person''': Can partly update a person.
* RE.15: '''Delete person''': Can delete a person (if no services are linked to the person).

=== Customer Employee (CE) ===
Definition of a Customer Employee (CE):
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000004
| Unique id of the person.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000002
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

| employeeOfId
| sstEmployeeOfUID
| 4000002
| Shows the customer (in this case), that the person is an employee of (multiple customers possible, N:M relation).
|-

|}

==== Customer Employee (CE) Rights ====
Sees the customer they belong to, themselves, their own people and their services. The following rights exist for a Customer Employee (CE), a Reseller Employee (RE) and a Service Provider Person (SPP):
* CE.00: '''Retrieve some customers''': Can retrieve the customer(s) they are an employee of.
* CE.01: '''Retrieve a customer''': Can retrieve one of the customer(s) they are an employee of.
* CE.02: '''Update a customer:''' Can update one of the customer(s) they are an employee of.
* CE.03: '''Partly Update a customer''': Can partly update one of the customer(s) they are an employee of.

* CE.04: '''Create a person''': Can create a person (including making them an employee of their customer(s)).
* CE.05: '''Retrieve all people''': Can retrieve all their people (of their customer(s)).
* CE.06: '''Retrieve a person''': Can retrieve one of their people (of their customer(s)).
* CE.07: '''Update a person:''' Can update a person (including making them an employee of their customer(s)).
* CE.08: '''Partly Update a person''': Can partly update a person.
* CE.09: '''Delete person''': Can delete a person (if no services are linked to the person).

=== Reseller Person (P) and Customer Person (P) ===
Definition of a Reseller Person (P) and Customer Person (P):
{| border="1" class="wikitable sortable"
! API Attribute
! LDAP Attribute
! Example
! Description
|-

| id
| uid
| 4000005
| Unique id of the person.
|-

| isActive
| sstIsActive
| true
| Is the person active or not. Only active people are allowed to authenticate themselves.
|-

| belongsToResellerId
| sstBelongsToResellerUID
| 4000000
| Shows the reseller, that the person belongs to (only one reseller possible, N:1 relation).
|-

| belongsToCustomerId
| sstBelongsToCustomerUID
| 4000002
| Shows the customer, that the person belongs to (only one customer possible, N:1 relation).
|-

|}

==== Reseller Person (P) and Customer Person (P) Rights ====
A Reseller Person (P) and Customer Person (P) act exactly the same. They see themselves and their own services.
Sees the customer they belong to, themselves, their own people and their services. The following rights exist for a Reseller Person (P), a Customer Person (P), a Customer Employee (CE), a Reseller Employee (RE) and a Service Provider Person (SPP):
* P.00: '''Retrieve a person''': Can retrieve themselves.
* P.01: '''Update a person:''' Can update themselves.
* P.02: '''Partly Update a person''': Can partly update themselves.

= REST API documentation =
=== Reserved Keywords ===
We have some special reserved keywords, which can no be used by the REST API:
* sort: Used for sorting.
* q: Full text search.
* page: Pagination.

=== Base URI ===
The RESTful web service has to be accessible via a secure HTTP (HTTPS) base URI, for instance <code>https://api.example.com/v1</code>.
The definition of the base URI is up to the provider of the service. The only requirements are the use of HTTPS and the presence of the service's version information, so that further changes are possible without breaking existing clients.

=== Client authentication and authorization ===
The service needs to authenticate each client via HTTP basic authentication by a user name and a corresponding password. If a unauthenticated client tries to access the service, it will response with a <code>401</code> (Unauthorized) HTTP [[#Error_codes_and_responses|error code]].

Furthermore the service must retrieve the authenticated users role and object ownership and respect their respective value when returning collections and elements and acting on HTTP methods. If a client tries to get, modify or delete an element for which it is not authorized, the services will response with a <code>403</code> (Forbidden) HTTP [[#Error_codes_and_responses|error code]] and includes a descriptive authorization validation message within the JSON error object.

To solely authentication a person, use the resource described under [[stoney core: Authentication Resource - REST API]].

=== Data interchange format ===
The service needs to accept and send all data in the JSON data interchange format via HTTP, encoded as UTF-8. Thus a client needs to accept and use the [http://tools.ietf.org/html/rfc4627 <code>application/json</code>] media type. Further media types might be supported in the future.

This results in the following required request and response headers:
{| class="wikitable sortable"
|-
! Request header
! Response header

|-
|<pre>
Accept: application/json
Accept-Charset: utf-8
</pre>
| <pre>Content-Type: application/json;charset=utf-8</pre>

|}

* If the client sends an <code>Accept</code> header with an unsupported value (at the moment only <code>application/json</code> is supported), the service will respond with a <code>406</code> (Not Acceptable) [[#Error codes and responses|error code]].
* If the client sends an <code>Accept-Charset</code> header with an unsupported value (at the moment only <code>utf-8</code> is supported), the service will respond with a <code>406</code> (Not Acceptable) [[#Error codes and responses|error code]].
* If no <code>Accept</code> header is sent, the server will use JSON, possibly pretty-printed and annotated.
* If no <code>Accept-Charset</code> header is sent, the server send the response with <code>utf-8</code> as charset.
* If the client sends a <code>Content-Type</code> other than <code>application/json</code> on a POST, PUT or PATCH request, the service will respond with a <code>415</code> (Unsupported Media Type) [[#Error codes and responses|error code]].
* If the client sends invalid JSON, the service will response with a <code>400</code> (Bad Request) HTTP [[#Error codes and responses|error code]] and a descriptive error message within the error object.
* When returning a <code>401</code>, a proper <code>WWW-Authenticate</code> header must be sent as well as documented in [http://tools.ietf.org/html/rfc7235#page-7 RFC7235 (or earlier HTTP 1.1/1.0 RFCs)].

Unless otherwise noted, the [http://tools.ietf.org/wg/httpbis/ HTTPbis RFCs] always apply.

Future extension:
Client may supply <code>application/vnd.org.stoney-cloud.api+json</code> as <code>Content-Type</code> to declare the requested schema/format of the data. This can then also be used to introduce additional versioning.

=== Error codes and responses ===
The service returns appropriate HTTP status codes for every request, the following table lists the commonly used codes:

{| class="wikitable sortable"
|-
! HTTP status code
! Text
! Description

|-
| 200
| OK
| Success.

|-
| 201
| Created
| A new resource was successfully created.

|-
| 400
| Bad Request
| The request was invalid. A descriptive error message will be sent within the response body.

|-
| 404
| Not Found
| The requested resource could not be found but may be available again in the future.

|-
| 406
| Not Acceptable
| The requested resource is only capable of generating content not acceptable according to the Accept headers sent in the request.

|-
| 401
| Unauthorized
| The client has failed or not yet tried to authenticate.

|-
| 403
| Forbidden
| The client is not allowed to access the requested resource.

|-
| 415
| Unsupported Media Type
| The request entity has a media type which the server or resource does not support. For example, sending XML instead of JSON in a POST, PUT or PATCH method.

|-
| 422
| Unprocessable Entity
| The request was well-formed but was unable to be followed due to semantic errors. For example, a client sends a invalid field value (numbers instead of characters) in a JSON object.

|-
| 428
| Precondition Required
| The client did not provide a proper ETag and/or Last-modification header when updating an object via PUT, see http://tools.ietf.org/html/rfc6585#section-3

|-
| 429
| Too Many Requests
| There were too many requests within a given time-period, see http://tools.ietf.org/html/rfc6585#section-4

|-
| 500
| Internal Server Error
| An internal error succoured. A descriptive error message will be sent within the response body.

|-
| 503
| Service Unavailable
| The service is temporary unavailable, because it is overloaded or down for maintenance

|}

Additionally the service returns a descriptive error object in case a HTTP error was returned (4xx) within the message body of the response. An error object consists of an error code and a human readable error message, with further detailed error messages if applicable.

<source lang='javascript'>
{
"error": {
"module": "core",
"code": 123,
"message": "Validation failed"
"details" : [
{
"module": "core",
"code" : 5432,
"field" : "firstName",
"message" : "First name cannot be longer than 35 characters"
},
{
"module": "core",
"code" : 5123,
"field" : "password",
"message" : "Password cannot be blank"
}
]
}
}
</source>

=== Mandatory headers ===

Besides the above mentioned headers, the following headers are mandatory.

* every answer to a GET reqest should always include <code>[http://en.wikipedia.org/wiki/HTTP_ETag ETag]</code> and <code>Last-Modified</code> header. This allows a proxy to cache requests and a client to revalidate already fetched data.
* the service must recognize <code>ETag</code>, <code>Last-Modified</code> and <code>Cache-Control: none</code> provided by the client and act accordingly.
* every answer to a GET request must include proper <code>Cache-Control</code> headers
* every PUT request to update an object must include the <code>ETag</code> provided by the <code>GET</code> request to fetch the object initially. The API must respond with an <code>428 (Precondition Required)</code> if the ETag is missing.

''Implementation notes'':
* one could use the internal LDAP attributes <code>entryCSN</code> and/or <code>modifyTimestamp</code> to generate an ETag via a hash function. In the case of business objects where multiple LDAP objects are aggregated for one exposed object, the hash can be generated over all constituent objects
* the <code>Last-Modified</code> header can be used to directly limit the search results when hitting the LDAP via the <code>modifyTimestamp</code> internal attribute. Ex. <code>modifytimestamp>=20060301000000Z</code>

=== Resources and HTTP methods ===
Resources are always nouns, and specified in plural (such as resellers, customers, users etc.), this prevents one from dealing with irregular pluralizations such as person/people.

The manipulation of resources happens via the HTTP request methods such as <code>GET</Code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code> and <code>PATCH</code>.
The following example illustrates the concept with a fictive user resource:
{| class="wikitable sortable"
|-
! HTTP request
! Description

|-
| <code>GET /users</code>
| Retrieves a list of users

|-
| <code>GET /users/12345678</code>
| Retrieves a specific user with user ID 12345678

|-
| <code>POST /users</code>
| Creates a new user

|-
| <code>PUT /users/12345678</code>
| Updates the user with user ID 12345678

|-
| <code>PATCH /users/12345678</code>
| Partly updates the user with user ID 12345678

|-
| <code>DELETE /users/12345678</code>
| Deletes the user with user ID 12345678

|-
| <code>DELETE /users</code>
| Deletes all users

|}

==== POST ====

On successful creation of an element, the service must return an URI string to the newly created element.

'''Example''':

Request:
<pre>
POST /v1/users/ HTTP 1.1
HOST: api.example.com
</pre>
<pre>
Accept: application/json
Content-Type: application/json
</pre>
<source lang='javascript'>
{
"usersName": "Mueller",
"usersType": "reseller",
}
</source>

Answer:
<pre>
HTTP/1.1 201 Created
</pre>
<pre>
Content-Type: application/json; charset=UTF-8
Location: https://api.example.com/v1/users/67890
</pre>
<source lang='javascript'>
{
"id": 67890,
"location": "https://api.example.com/v1/users/67890",
}
</source>

=== Relations ===
Resources which stand in relation with each other are represented as URIs (scoping):
* <code>/v1/resellers/4000001/customers</code> -> collection resource (all customers of reseller with uid=4000001)
* <code>/v1/resellers/4000001/customers/4000002</code> -> resource (the customer with uid=4000002 of reseller with uid=4000001)

The following queries have the same effect as the URIs from above:
* <code>/v1/customers?belongsToResellerUID=4000001</code> -> collection resource (all customers of reseller with uid=4000001)
* <code>/v1/customers/4000002</code> -> resource (the customer with uid=4000002 of reseller with uid=4000001)

Relations are always returned as URIs, which the client can hit.

Future possibilities (sub objects) which aren't currently implemented:
* If a relation can only exist within another resource, it will be represent by its URI, for example: <code>/threads/123/messages/45</code>. This URI represents the message with ID #45 of the forum thread with ID #123.

=== Filtering, sorting and searching ===
Filter, sort and search requests are added as query parameters to the resource URI.

For '''filtering''' the objects returned by a resource URI, the name of an object's attribute is added as a query parameter with the required value. For example, get all active user elements:
GET /v1/users?status=active

For '''sorting''' the objects returned by a resource URI, the query parameter <code>sort</code> is added with the object's sort attribute(s) as the value. The following example will sort users by lastname and firstname in lexicographic ascending order:
GET /v1/users?sort=lastname,firstname

The following will sort users by lastname in lexicographic descending and firstname in lexicographic ascending order:
GET /v1/users?sort=-lastname,firstname

The following will sort users by lastname and by firstname in lexicographic descending order:
GET /v1/users?sort=-lastname,-firstname

For '''full text search''' the objects returned by a resource URI, the query parameter <code>q</code> is added with the value to search for. For example
GET /v1/users?q=Muell
will return users named <code>Mueller</code> as well as the ones living at <code>Muellhaldenstrasse</code>.

For full text search over all the available resources visit [[stoney core: Search Resource - REST API]].

=== Pagination ===
Responses with multiple items will be '''limited and paginated to 30 items''' per default (defined on server-side). Further items can be accessed by appending the <code>page</code> query parameter. The number of items to be returned can be '''raised to a maximum of 100''' (defined on server-side), by specifying the <code>per_page</code> query parameter.

For example, to request page number 3 with 40 items per page, a client would send the following GET request:
<pre>
GET /v1/people?page=3&per_page=40
</pre>

If pagination is requested by the client and/or enforced by the server (e.g. if the number of available records is larger than the default count and no pagination requested), the service returns [http://tools.ietf.org/html/rfc5988#section-6.2.2 official registered link relation types] (<code>next</code>, <code>prev</code>, <code>first</code>, <code>last</code>) within the HTTP [http://tools.ietf.org/html/rfc5988#section-5 Link header field] for pagination use:
<pre>
Content-Type: Content-Type: application/json; charset=UTF-8
Link: <https://api.example.com/v1/resellers?page=1&per_page=30>; rel="first",
<https://api.example.com/v1/resellers?page=2&per_page=30>; rel="prev",
<https://api.example.com/v1/resellers?page=4&per_page=30>; rel="next",
<https://api.example.com/v1/resellers?page=10&per_page=30>; rel="last"
X-Total-Count: 295
</pre>

The client MUST use those pagination links, rather than constructing the URLs by itself.

Furthermore the service sets a custom header <code>X-Total-Count</code> containing the (estimation of) total number of records.

=== Field specifications and limitations ===
@TBD: Do we want a possibility to specify which fields should be return on a GET request? This could either be used to save further requests to element URIs, if one fetches items from a collection URL, or to reduce the required amount of data to be transferred if one only uses a few attributes from a response. If yes, a <code>fields</code> query parameter should be added to a resource which takes a comma separated list of field names, such as <code>https://api.example.com/v1/users?fields=firstname,lastname</code>.

Maybe. In a collection there shouldn't be as many elements returned such that this may be come a problem. On the other hand, if we return large sets, we should rather use caching properly. Making it possible to specify fields makes cachign even harder. See for example https://blog.apigee.com/detail/restful_api_design_can_your_api_give_developers_just_the_information/ --[[User:Tiziano|Tiziano]] ([[User talk:Tiziano|talk]]) 11:47, 11 December 2013 (CET)

=== Input validations ===
The service validates all input it receives from a client and returns a <code>422</code> (Unprocessable Entity) HTTP [[#Error_codes_and_responses|error code with a descriptive error object]].

= Notes =
* Resource for modules => which modules are available for a given role and belong to which category
* Nested URLs vs. filter via get parameter => <code>/users/<UID>/products</code> vs. <code>/products/?userId=<UID></code>, (choose a better word for product?)
* Sudo mechanism, via custom HTTP header, for example <code>X-USER</code>

[[Category:REST API]][[Category:stoney core]]

stoney backup: Server set-up

2014-06-19T08:15:43Z

Chrigu: /* writeAccountSize.pl */

= Abstract =
This document describes server setup for the stoney cloud (Online) Backup service, built upon the [http://www.gentoo.org/ Gentoo] Linux distribution.

= Overview =
After working through this documentation, you will be able to set up and configure your own (Online) Backup service server.

= Software Installation =

== Requirements ==
A working stoney cloud, installed according to [[stoney cloud: Single-Node Installation]] or [[stoney cloud: Multi-Node Installation]].

== Keywords & USE-Flags ==
For a minimal OpenLDAP directory installation:
echo "net-nds/openldap minimal sasl" >> /etc/portage/package.use
echo "net-nds/openldap ~amd64" >> /etc/portage/package.keywords

NSS and PAM modules for lookups using LDAP:
echo "sys-auth/nss-pam-ldapd sasl" >> /etc/portage/package.use
echo "sys-auth/nss-pam-ldapd ~amd64" >> /etc/portage/package.keywords
echo "sys-fs/quota ldap" >> /etc/portage/package.use

echo "=app-admin/jailkit-2.16 ~amd64" >> /etc/portage/package.keywords

For the prov-backup-rsnapshot daemon:
echo "dev-perl/Net-SMTPS ~amd64" >> /etc/portage/package.keywords
echo "perl-core/Switch ~amd64" >> /etc/portage/package.keywords

To build puttygen only without X11:
echo "net-misc/putty ~amd64" >> /etc/portage/package.keywords
echo "net-misc/putty -gtk" >> /etc/portage/package.use

== Emerge ==
emerge -va nss-pam-ldapd \
quota \
net-misc/putty \
app-admin/jailkit \
sys-apps/haveged \
net-misc/putty \
sys-apps/sst-backup-utils \
sys-apps/sst-prov-backup-rsnapshot

To list the dependencies of ebuilds, you can use <code>equery</code>:
equery depgraph sst-backup-utils
<pre>
* Searching for sst-backup-utils ...

* dependency graph for sys-apps/sst-backup-utils-0.1.0
`-- sys-apps/sst-backup-utils-0.1.0 amd64
`-- dev-perl/PerlUtil-0.1.0 (>=dev-perl/PerlUtil-0.1.0) amd64
`-- virtual/perl-Sys-Syslog-0.320.0 (virtual/perl-Sys-Syslog) amd64
`-- dev-perl/perl-ldap-0.530.0 (dev-perl/perl-ldap) amd64
`-- dev-perl/XML-Simple-2.200.0 (dev-perl/XML-Simple) amd64
`-- dev-perl/Config-IniFiles-2.780.0 (dev-perl/Config-IniFiles) amd64
`-- dev-perl/XML-Validator-Schema-1.100.0 (dev-perl/XML-Validator-Schema) amd64
`-- dev-perl/Date-Calc-6.300.0 (dev-perl/Date-Calc) amd64
`-- dev-perl/DateManip-6.310.0 (dev-perl/DateManip) amd64
`-- dev-perl/Schedule-Cron-Events-1.930.0 (dev-perl/Schedule-Cron-Events) amd64
`-- dev-perl/DateTime-Format-Strptime-1.520.0 (dev-perl/DateTime-Format-Strptime) amd64
`-- dev-perl/XML-SAX-0.990.0 (dev-perl/XML-SAX) amd64
`-- virtual/perl-MIME-Base64-3.130.0-r2 (virtual/perl-MIME-Base64) amd64
`-- dev-perl/Authen-SASL-2.160.0 (dev-perl/Authen-SASL) amd64
`-- dev-perl/Net-SMTPS-0.30.0 (dev-perl/Net-SMTPS) ~amd64
`-- dev-perl/text-template-1.450.0 (dev-perl/text-template) amd64
`-- virtual/perl-Getopt-Long-2.380.0-r2 (virtual/perl-Getopt-Long) amd64
`-- dev-perl/Parallel-ForkManager-1.20.0 (dev-perl/Parallel-ForkManager) amd64
`-- dev-perl/Time-Stopwatch-1.0.0 (dev-perl/Time-Stopwatch) amd64
`-- app-backup/rsnapshot-1.3.1-r1 (app-backup/rsnapshot) amd64
[ sys-apps/sst-backup-utils-0.1.0 stats: packages (20), max depth (1) ]
</pre>

For more information, visit the [http://www.gentoo.org/doc/en/gentoolkit.xml Gentoolkit] page.

= Base Server Software Configuration =
== OpenSSH ==
=== OpenSSH Configuration ===
Configure the OpenSSH daemon:
<source lang="bash">
vi /etc/ssh/sshd_config
</source>

Set following options:
<source lang="bash">
PubkeyAuthentication yes
PasswordAuthentication yes
UsePAM yes
Subsystem sftp internal-sftp
</source>

Make sure, that <code>Subsystem sftp internal-sftp</code> is the last line in the configuration file.

We want to reduce the numbers of chroot environments in one folder. As the <code>ChrootDirectory</code> configuration option only allows <code>%h</code> (home directory of the user) and <code>%u</code> (username of the user), we need to create the necessary matching rules in the form of:
<source lang="bash">
Match User *000
ChrootDirectory /var/backup/000/%u
AuthorizedKeysFile /var/backup/000/%u/%h/.ssh/authorized_keys
Match
Match User *001
ChrootDirectory /var/backup/001/%u
AuthorizedKeysFile /var/backup/001/%u/%h/.ssh/authorized_keys
Match
...
Match User *999
ChrootDirectory /var/backup/999/%u
AuthorizedKeysFile /var/backup/999/%u/%h/.ssh/authorized_keys
Match
</source>

The creation of the matching rules is done by executing the following bash commands:
<source lang="bash">
FILE=/etc/ssh/sshd_config;

for x in {0..999} ; do \
printf "Match User *%03d\n" $x >> ${FILE}; \
printf " ChrootDirectory /var/backup/%03d/%%u\n" $x >> ${FILE}; \
printf " AuthorizedKeysFile /var/backup/%03d/%%u/%%h/.ssh/authorized_keys\n" $x >> ${FILE}; \
printf "Match\n" >> ${FILE}; \
done
</source>

Don't forget to restart the OpenSSH daemon:
<source lang="bash">
/etc/init.d/sshd restart
</source>

=== OpenSSH Host Keys ===
If you migrate from a existing backup server, you might want to copy the ssh host keys to the new server. If you do so clients want see a difference between the two hosts as the fingerprint remains the same. Copy the following files from the existing host to the new:
* /etc/ssh/ssh_host_dsa_key
* /etc/ssh/ssh_host_ecdsa_key
* /etc/ssh/ssh_host_key
* /etc/ssh/ssh_host_rsa_key
* /etc/ssh/ssh_host_dsa_key.pub
* /etc/ssh/ssh_host_ecdsa_key.pub
* /etc/ssh/ssh_host_key.pub
* /etc/ssh/ssh_host_rsa_key.pub

Set the correct permissions on the new host:
chmod 600 /etc/ssh/ssh_host_dsa_key /etc/ssh/ssh_host_ecdsa_key /etc/ssh/ssh_host_key /etc/ssh/ssh_host_rsa_key
chmod 644 /etc/ssh/*.pub

And restart the ssh daemon. ''Caution'': do not close your existing ssh session as long as you are not sure the ssh daemon has restarted properly and you can login again.
/etc/init.d/sshd restart

== OpenLDAP ==
=== /etc/hosts ===
Update the <code>/etc/hosts</code> with the LDAP server:
/etc/hosts

# VIP of the LDAP Server
31.216.40.4 ldapm.stoney-cloud.org

=== Root CA Certificate Installation ===
Install the root CA certificate into the OpenSSL default certificate storage directory:
fqdn="cloud.stoney-cloud.org" # The fully qualified domain name of the server containing the root certificate.

cd /etc/ssl/certs/
wget --no-check-certificate https://${fqdn}/ca/FOSS-Cloud_CA.cert.pem
chown root:root /etc/ssl/certs/FOSS-Cloud_CA.cert.pem
chmod 444 /etc/ssl/certs/FOSS-Cloud_CA.cert.pem

Rebuild the CA hashes
c_rehash /etc/ssl/certs/

=== /etc/openldap/ldap.conf ===
Update the <code>/etc/openldap/ldap.conf</code>LDAP configuration file/environment variables:
/etc/openldap/ldap.conf

<pre>
# Used to specify a size limit to use when performing searches. The number should be an
# non-negative integer. SIZELIMIT of zero (0) specifies unlimited search size.
SIZELIMIT 20000

# Used to specify a time limit to use when performing searches. The number should be an
# non-negative integer. TIMELIMIT of zero (0) specifies unlimited search time to be used.
TIMELIMIT 45

# Specify how aliases dereferencing is done. DEREF should be set to one of never, always, search,
# or find to specify that aliases are never dereferenced, always dereferenced, dereferenced when
# searching, or dereferenced only when locating the base object for the search. The default is to
# never dereference aliases.
DEREF never

# Specifies the URI(s) of an LDAP server(s) to which the LDAP library should connect. The URI
# scheme may be either ldapor ldaps which refer to LDAP over TCP and LDAP over SSL (TLS)
# respectively. Each server's name can be specified as a domain- style name or an IP address
# literal. Optionally, the server's name can followed by a ':' and the port number the LDAP
# server is listening on. If no port number is provided, the default port for the scheme is
# used (389 for ldap://, 636 for ldaps://). A space separated list of URIs may be provided.
URI ldaps://ldapm.stoney-cloud.org

# Used to specify the default base DN to use when performing ldap operations. The base must be
# specified as a Distinguished Name in LDAP format.
BASE dc=stoney-cloud,dc=org

# This is a local copy of the certificate of the certificate authority
# used to sign the server certificate for the LDAP server I am using
TLS_CACERT /etc/ssl/certs/FOSS-Cloud_CA.cert.pem
</pre>

Check you configuration by doing a search:
ldapsearch -v -H "ldaps://ldapm.stoney-cloud.org" \
-b "dc=stoney-cloud,dc=org" \
-D "cn=Manager,dc=stoney-cloud,dc=org" \
-s one "(objectClass=*)" \
-LLL -W

The result should look something like:
ldap_initialize( ldaps://ldapm.stoney-cloud.org:636/??base )
filter: (objectClass=*)
requesting: All userApplication attributes
dn: ou=administration,dc=stoney-cloud,dc=org
objectClass: top
objectClass: organizationalUnit
ou: administration
...

== Random Number Generator (haveged) ==
Tools like putty are dependent on random numbers to be able to create certificates.

=== haveged - Generate random numbers and feed linux random device ===
The haveged daemon doesn't need any special configuration, therefore you can start it from the command line interface:
/etc/init.d/haveged start

Check, if the start was successful:
ps auxf | grep haveged

root 18001 1.0 0.0 7420 3616 ? Ss 08:48 0:00 /usr/sbin/haveged -r 0 -w 1024 -v 1

Add the haveged daemon to the default run level:
rc-update add haveged default

== nss-pam-ldapd ==
=== nslcd.conf — configuration file for LDAP nameservice daemon ===
/etc/nslcd.conf

<pre>
# This is the configuration file for the LDAP nameservice
# switch library's nslcd daemon. It configures the mapping
# between NSS names (see /etc/nsswitch.conf) and LDAP
# information in the directory.
# See the manual page nslcd.conf(5) for more information.

# The user and group nslcd should run as.
uid nslcd
gid nslcd

# The uri pointing to the LDAP server to use for name lookups.
# Multiple entries may be specified. The address that is used
# here should be resolvable without using LDAP (obviously).
#uri ldap://127.0.0.1/
#uri ldaps://127.0.0.1/
#uri ldapi://%2fvar%2frun%2fldapi_sock/
# Note: %2f encodes the '/' used as directory separator
uri ldaps://ldapm.tombstone.ch

# The LDAP version to use (defaults to 3
# if supported by client library)
#ldap_version 3

# The distinguished name of the search base.
base dc=stoney-cloud,dc=org

# The distinguished name to bind to the server with.
# Optional: default is to bind anonymously.
binddn cn=Manager,dc=stoney-cloud,dc=org

# The credentials to bind with.
# Optional: default is no credentials.
# Note that if you set a bindpw you should check the permissions of this file.
bindpw myverysecretpassword

# The distinguished name to perform password modifications by root by.
#rootpwmoddn cn=admin,dc=example,dc=com

# The default search scope.
#scope sub
#scope one
#scope base

# Customize certain database lookups.
#base group ou=Groups,dc=example,dc=com
base group ou=groups,ou=backup,ou=services,dc=stoney-cloud,dc=org
base passwd ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
base shadow ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
#scope group onelevel
#scope hosts sub

#filter group (&(objectClass=posixGroup)(sstIsActive=TRUE))
filter passwd (&(objectClass=posixAccount)(sstIsActive=TRUE))
filter shadow (&(objectClass=shadowAccount)(sstIsActive=TRUE))

# Bind/connect timelimit.
#bind_timelimit 30

# Search timelimit.
#timelimit 30

# Idle timelimit. nslcd will close connections if the
# server has not been contacted for the number of seconds.
#idle_timelimit 3600

# Use StartTLS without verifying the server certificate.
#ssl start_tls
tls_reqcert never

# CA certificates for server certificate verification
#tls_cacertdir /etc/ssl/certs
#tls_cacertfile /etc/ssl/ca.cert

# Seed the PRNG if /dev/urandom is not provided
#tls_randfile /var/run/egd-pool

# SSL cipher suite
# See man ciphers for syntax
#tls_ciphers TLSv1

# Client certificate and key
# Use these, if your server requires client authentication.
#tls_cert
#tls_key

# Mappings for Services for UNIX 3.5
#filter passwd (objectClass=User)
#map passwd uid msSFU30Name
#map passwd userPassword msSFU30Password
#map passwd homeDirectory msSFU30HomeDirectory
#map passwd homeDirectory msSFUHomeDirectory
#filter shadow (objectClass=User)
#map shadow uid msSFU30Name
#map shadow userPassword msSFU30Password
#filter group (objectClass=Group)
#map group member msSFU30PosixMember

# Mappings for Services for UNIX 2.0
#filter passwd (objectClass=User)
#map passwd uid msSFUName
#map passwd userPassword msSFUPassword
#map passwd homeDirectory msSFUHomeDirectory
#map passwd gecos msSFUName
#filter shadow (objectClass=User)
#map shadow uid msSFUName
#map shadow userPassword msSFUPassword
#map shadow shadowLastChange pwdLastSet
#filter group (objectClass=Group)
#map group member posixMember

# Mappings for Active Directory
#pagesize 1000
#referrals off
#idle_timelimit 800
#filter passwd (&(objectClass=user)(!(objectClass=computer))(uidNumber=*)(unixHomeDirectory=*))
#map passwd uid sAMAccountName
#map passwd homeDirectory unixHomeDirectory
#map passwd gecos displayName
#filter shadow (&(objectClass=user)(!(objectClass=computer))(uidNumber=*)(unixHomeDirectory=*))
#map shadow uid sAMAccountName
#map shadow shadowLastChange pwdLastSet
#filter group (objectClass=group)

# Alternative mappings for Active Directory
# (replace the SIDs in the objectSid mappings with the value for your domain)
#pagesize 1000
#referrals off
#idle_timelimit 800
#filter passwd (&(objectClass=user)(objectClass=person)(!(objectClass=computer)))
#map passwd uid cn
#map passwd uidNumber objectSid:S-1-5-21-3623811015-3361044348-30300820
#map passwd gidNumber objectSid:S-1-5-21-3623811015-3361044348-30300820
#map passwd homeDirectory "/home/$cn"
#map passwd gecos displayName
#map passwd loginShell "/bin/bash"
#filter group (|(objectClass=group)(objectClass=person))
#map group gidNumber objectSid:S-1-5-21-3623811015-3361044348-30300820

# Mappings for AIX SecureWay
#filter passwd (objectClass=aixAccount)
#map passwd uid userName
#map passwd userPassword passwordChar
#map passwd uidNumber uid
#map passwd gidNumber gid
#filter group (objectClass=aixAccessGroup)
#map group cn groupName
#map group gidNumber gid
</pre>

=== nsswitch.conf - Name Service Switch configuration file ===
/etc/nsswitch.conf

<pre>
passwd: files ldap
shadow: files ldap
group: files ldap

# passwd: db files nis
# shadow: db files nis
# group: db files nis

hosts: files dns
networks: files dns

services: db files
protocols: db files
rpc: db files
ethers: db files
netmasks: files
netgroup: files
bootparams: files

automount: files
aliases: files
</pre>

=== system-auth ===
vi /etc/pam.d/system-auth

<pre>
auth required pam_env.so
auth sufficient pam_unix.so try_first_pass likeauth nullok
auth sufficient pam_ldap.so minimum_uid=1000 use_first_pass
auth required pam_deny.so

account required pam_unix.so
account sufficient pam_ldap.so minimum_uid=1000 use_first_pass

password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
password required pam_unix.so try_first_pass use_authtok nullok sha512 shadow
password sufficient pam_ldap.so minimum_uid=1000 use_first_pass
password required pam_deny.so

session required pam_limits.so
session required pam_env.so
session required pam_unix.so
session sufficient pam_ldap.so minimum_uid=1000 use_first_pass
</pre>

=== Test the Setup ===
nslcd -d

=== Update the Default Run Levels ===
rc-update add nslcd default
rc-update add nscd default

=== Start the necessary Daemons ===
/etc/init.d/nslcd start
/etc/init.d/nscd start

== Quota ==
=== 32-bit Project Identifier Support ===
We need to enable 32-bit project identifier support (PROJID32BIT feature) for our naming scheme (uid numbers larger than 65'536), which is already the default on the stepping stone virtual machines:
mkfs.xfs '''-i projid32bit=1''' /dev/vg-local-01/var

=== Update /etc/fstab and Mount ===
Make sure, that you have user quota (uqota) and project quota (pquota) set as options on the chosen mount point in /etc/fstab. For example:
LABEL=LV-VAR /var xfs noatime,discard,inode64,uquota,pquota 0 2

reboot

Check, if everything went ok:
df -h | grep var

/dev/mapper/vg--local--01-var 1023G 220G 804G 22% /var

=== Verify ===
Some important options for xfs_quota:
* -x: Enable expert mode.
* -c: Pass arguments on the command line. Multiple arguments may be given.

Remount the file system /var and check, if /var has the desired values:
xfs_quota -x -c state /var

As you can see (items marked bold), we have achieved our goal:
User quota state on /var (/dev/mapper/vg--local--01-var)
Accounting: '''ON'''
Enforcement: '''ON'''
Inode: #131 (1 blocks, 1 extents)
Group quota state on /var (/dev/mapper/vg--local--01-var)
Accounting: OFF
Enforcement: OFF
Inode: #132 (1 blocks, 1 extents)
Project quota state on /var (/dev/mapper/vg--local--01-var)
Accounting: '''ON'''
Enforcement: '''ON'''
Inode: #132 (1 blocks, 1 extents)
Blocks grace time: [7 days 00:00:30]
Inodes grace time: [7 days 00:00:30]
Realtime Blocks grace time: [7 days 00:00:30]

=== User Quotas ===
==== Adding a User Quota ====
Set a quota of 1 Gigabyte for the user 4000187 (the values are in kilobytes, so 1048576 kilobyte are 1024 megabytes which corresponds to 1 gigabyte):
xfs_quota -x -c 'limit bhard=1048576k 4000187' /var

Or in bytes:
xfs_quota -x -c 'limit bhard=1073741824 4000187' /var

Read the quota information for the user 4000187:
xfs_quota -x -c 'quota -v -N -u 4000187' /var

/dev/mapper/vg--local--01-var 0 0 1048576 00 [--------] /var

If the user has data in the project, that belongs to him, the result will change:
/dev/mapper/vg--local--01-var 512000 0 1048576 00 [--------] /var

==== Modifiying a User Quota ====
To modify a users quota, you just set a new quota (limit):
xfs_quota -x -c 'limit bhard=1048576k 4000187' /var

Read the quota information for the user 4000187:
xfs_quota -x -c 'quota -v -N -u 4000187' /var

/dev/mapper/vg--local--01-var 0 0 1048576 00 [--------] /var

If the user has data in the project, that belongs to him, the result will change:
/dev/mapper/vg--local--01-var 512000 0 1048576 00 [--------] /var

==== Removing a User Quota ====
Removing a quota for a user:
xfs_quota -x -c 'limit bhard=0 4000187' /var

The following command should give you an empty result:
xfs_quota -x -c 'quota -v -N -u 4000187' /var

=== Project (Directory) Quotas ===
==== Adding a Project (Directory) Quota ====
The XFS file system additionally allows you to set quotas on individual directory hierarchies in the file system that are known as managed trees. Each managed tree is uniquely identified by a project ID and an optional project name. We'll use the following values in the examples:
* project_ID: The uid of the online backup account (4000187).
* project_name: The uid of the online backup account (4000187). This could be a human readable name.
* mountpoint: The mountpoint of the xfs-filesystem (/var). See the <code>/etc/fstab</code> entry from above.
* directory: The directory of the project (187/4000187), starting from the mountpoint of the xfs-filesystem (/var).

Define a unique project ID for the directory hierarchy in the <code>/etc/projects</code> file (project_ID:mountpoint/directory):
echo "4000187:/var/backup/187/4000187/home/4000187" >> /etc/projects

Create an entry in the <code>/etc/projid</code> file that maps a project name to the project ID (project_name:project_ID):
echo "4000187:4000187" >> /etc/projid

Set Project:
xfs_quota -x -c 'project -s -p /var/backup/187/4000187/home/4000187 4000187' /var

Set Quota (limit) on Project:
xfs_quota -x -c 'limit -p bhard=1048576k 4000187' /var

Check your Quota (limit)
xfs_quota -x -c 'quota -p 4000187' /var

Check the Quota:
* <code>-v</code>: increase verbosity in reporting (also dumps zero values).
* <code>-N</code>: suppress the initial header.
* <code>-p</code>: display project quota information.
* <code>-h</code>: human readable format.
xfs_quota -x -c 'quota -v -N -p 4000187' /var

/dev/mapper/vg--local--01-var 0 0 1048576 00 [--------] /var

If you copied data into the project, the output will look something like:
/dev/mapper/vg--local--01-var 512000 0 1048576 00 [--------] /var

To give you an overall view of the whole system:
xfs_quota -x -c report /var

<pre>
User quota on /var (/dev/mapper/vg--local--01-var)
Blocks
User ID Used Soft Hard Warn/Grace
---------- --------------------------------------------------
root 1024000 0 0 00 [--------]
4000187 0 0 1048576 00 [--------]

Project quota on /var (/dev/mapper/vg--local--01-var)
Blocks
Project ID Used Soft Hard Warn/Grace
---------- --------------------------------------------------
4000187 512000 0 1048576 00 [--------]
</pre>

==== Modifying a Project (Directory) Quota ====
To modify a project (directory) quota, you just set an new quota (limit) on the chosen project:
xfs_quota -x -c 'limit -p bhard=1048576k 4000187' /var

Check your quota (limit)
xfs_quota -x -c 'quota -p 4000187' /var

==== Removing a Project (Directory) Quota ====
Removing a quota from a project:
xfs_quota -x -c 'limit -p bhard=0 4000187' /var

Chreck the results:
xfs_quota -x -c report /var

<pre>
User quota on /var (/dev/mapper/vg--local--01-var)
Blocks
User ID Used Soft Hard Warn/Grace
---------- --------------------------------------------------
root 512000 0 0 00 [--------]
4000187 0 0 1024 00 [--------]
</pre>

As you can see, the line with the Project ID 4000187 has disappeared:
4000187 512000 0 1048576 00 [--------]

Don't forget to remove the project from <code>/etc/projects</code> and <code>/etc/projid</code>:
sed -i -e '/4000187/d' /etc/projects
sed -i -e '/4000187/d' /etc/projid

=== Some important notes concerning XFS ===
# The '''quotacheck''' command has no effect on XFS filesystems. The first time quota accounting is turned on (at mount time), XFS does an automatic quotacheck internally; afterwards, the quota system will always be completely consistent until quotas are manually turned off.
# There is '''no need for quota file(s)''' in the root of the XFS filesystem.

== prov-backup-rsnapshot ==
Install the [[stoney_backup:_prov-backup-rsnapshot | prov-backup-rsnasphot ]] daemon script using the package manager:
<pre>
emerge -va sys-apps/sst-prov-backup-rsnapshot
</pre>

=== Configuration ===
If it is the first provisioning module running on this server (very likely) you first have to configure the provisioning daemon (you can skip this step if you have already another provisioning module running on this server)

==== Provisioning global configuration ====
The global configuration for the provisioning daemon applies to all provisioning modules (@PAT: how where they installed? --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 09:58, 19 June 2014 (CEST)) running on the server. This configuration therefore contains information about the provisioning daemon itself and no information at all about the specific modules.
/etc/Provisioning/Global.conf
<pre>
# Copyright (C) 2012 stepping stone GmbH
# Switzerland
# http://www.stepping-stone.ch
# support@stepping-stone.ch
#
# Authors:
# Pat Kläy <pat.klaey@stepping-stone.ch>
#
# Licensed under the EUPL, Version 1.1.
#
# You may not use this work except in compliance with the
# Licence.
# You may obtain a copy of the Licence at:
#
# http://www.osor.eu/eupl
#
# Unless required by applicable law or agreed to in
# writing, software distributed under the Licence is
# distributed on an "AS IS" basis,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
# express or implied.
# See the Licence for the specific language governing
# permissions and limitations under the Licence.
#

[Global]
# If true the script logs every information to the log-file.
LOG_DEBUG = 0

# If true the script logs additional information to the log-file.
LOG_INFO = 1

#If true the script logs warnings to the log-file.
LOG_WARNING = 1

#If true the script logs errors to the log-file.
LOG_ERR = 1

# The number of seconds to wait before retry contacting the backend server during startup.
SLEEP = 10

# Number of backend server connection retries during startup.
ATTEMPTS = 3

[Operation Mode]
# The number of seconds to wait before retry contacting the backend server in case of a service interruptions.
SLEEP = 30

# Number of backend server connection retries in case of a service interruptions.
ATTEMPTS = 3

[Mail]
# Error messages are sent to the mail configured below.
SENDTO = <YOUR-MAIL-ADDRESS>
HOST = mail.stepping-stone.ch
PORT = 587
USERNAME = <YOUR-NOTIFICATION-EMAIL-ADDRESS>
PASSWORD = <PASSWORD>
FROMNAME = Provisioning daemon
CA_DIR = /etc/ssl/certs
SSL = starttls
AUTH_METHOD = LOGIN

# Additionally, you can be informed about creation, modification and deletion of services.
WANTINFOMAIL = 1
</pre>

==== Provisioning daemon prov-backup-rsnapshot module ====
The module specific configuration is located in /etc/Provisioning/<Service>/<Type>.conf. In the case of the prov-backup-rsnapshot module this is <code>/etc/Provisioning/Backup/Rsnapshot.conf</code>. (Note: Comments starting with /* are not in the configuration file, they are only in the wiki to add some additional information)

<pre>
# Copyright (C) 2013 stepping stone GmbH
# Switzerland
# http://www.stepping-stone.ch
# support@stepping-stone.ch
#
# Authors:
# Pat Kläy <pat.klaey@stepping-stone.ch>
#
# Licensed under the EUPL, Version 1.1.
#
# You may not use this work except in compliance with the
# Licence.
# You may obtain a copy of the Licence at:
#
# http://www.osor.eu/eupl
#
# Unless required by applicable law or agreed to in
# writing, software distributed under the Licence is
# distributed on an "AS IS" basis,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
# express or implied.
# See the Licence for the specific language governing
# permissions and limitations under the Licence.
#

/* If you want, you can override the log information from the global configuration file this might be useful for debugging */
[Global]
# If true the script logs every information to the log-file.
LOG_DEBUG = 1

# If true the script logs additional information to the log-file.
LOG_INFO = 1

#If true the script logs warnings to the log-file.
LOG_WARNING = 1

#If true the script logs errors to the log-file.
LOG_ERR = 1

/* Specify the hosts fully qualified domain name. This name will be used to perform some checks and also appear in the information and error mails */
ENVIRONMENT = <FQDN>

[Database]
BACKEND = LDAP
SERVER = ldaps://ldapm.tombstone.org
PORT = 636
ADMIN_USER = cn=Manager,dc=stoney-cloud,dc=org
ADMIN_PASSWORD = <PASSWORD>
SERVICE_SUBTREE = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
COOKIE_FILE = /etc/Provisioning/Backup/rsnapshot.cookie
DEFAULT_COOKIE = rid=001,csn=
SEARCH_FILTER = (&(entryCSN>=%entryCSN%)(sstProvisioningState=0))

/* Specifies the service itself. As it is the prov-backup-rsnapshot module, the SERVICE is "Backup" and the TYPE is "Rsnapshot".
* The MODUS is as usual selfcare and the TRANSPORTAPI is LocalCLI. This is because the daemon is running on the same host as the
* backup accounts are provisioned and the commands can be executed on this host using the cli.
* For more information about MODUS and TRANSPORTAPI see https://int.stepping-stone.ch/wiki/provisioning.pl#Service_Konfiguration
*/
[Service]
MODUS = selfcare
TRANSPORTAPI = LocalCLI
SERVICE = Backup
TYPE = Rsnapshot

SYSLOG = prov-backup-rsnapshot

/* For the TRANSPORTAPI LocalCLI there is no gateway required because there is no connection to establish. So set HOST, USER and
* DSA_FILE to whatever you want. Don't leave it blank, otherwise the provisioning daemon would log some error messages saying
* these attributes are empty
*/
[Gateway]
HOST = localhost
USER = provisioning
DSA_FILE = none

/* Information about the backup itself (how to setup everything). Note that the %uid% int the RSNAPSHOT_CONFIG_FILE parameter will
* be replaced by the accounts UID. The script CREATE_CHROOT_CMD was installed with the prov-backup-rsnapshot module, so do not
* change this parameter. The quota parameters (SET_QUOTA_CMD, MOUNTPOINT, QUOTA_FILE, PROJECTS_FILE and PROJID_FILE) represent
* the quota setup as described on http://wiki.stoney-cloud.org/index.php/stoney_backup:_Server_set-up#Quota. If you followed this
* manual, you can copy-paste them into your configuration file, otherwise adapt them according to your quota setup.
*/
[Backup]
RSNAPSHOT_CONFIG_FILE = /etc/rsnapshot/rsnapshot.conf.%uid%
SET_QUOTA_CMD = /usr/sbin/xfs_quota
CREATE_CHROOT_CMD = /usr/libexec/createBackupDirectory.sh
MOUNTPOINT = /var
QUOTA_FILE = /etc/backupSize
PROJECTS_FILE = /etc/projects
PROJID_FILE = /etc/projid
</pre>

== backup utils ==
Install the backup utils (multiple scripts which help you to manage and monitor your backup server and backup accounts) using the package manager. For more information about the scripts please see the [[stoney_backup:_Server_set-up#stoney_backup_Service_Software | stoney backup Service Software]] section.
<pre>
emerge -va sys-apps/sst-backup-utils
</pre>
=== Configuration ===
Please refer to the configuration sections for the different scripts in [[stoney_backup:_Server_set-up#stoney_backup_Service_Software | stoney backup Service Software]].

= stoney backup Service Software =
The stoney backup Service comes along with multiple scripts which help you to manage and monitor your backup server and accounts:

We use rsnapshot - remote filesystem snapshot utility for the actual snapshots and a handful of wrapper scripts, that do things like:
* Read the users and their settings from the LDAP directory.
* Execute rsnapshot according to the users settings.
* Write the backup quotas backup (incoming), iterations (.snapshots) and free space to the users local backupSize file and update the LDAP directory.
* Inform the reseller, customer or user (depending on the settings in the LDAP directory) via mail, if the quota limit has been reached.
* Depending on the users settings in the LDAP directory, warning mail will be sent to the reseller, customer or user, if a backup was not executed on time.

== writeAccountSize.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeAccountSize.pl</code> by the <code>sys-apps/sst-backup-utils</code> package and does the following:
@PAT: Please add a link to the current Git repository. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 10:15, 19 June 2014 (CEST)
* Calculates the used disk space (backup and iterations) for a given account and writes the corresponding values to:
*# The LDAP backend (used by the selfcare webinterface to display quota information):
*#* Backup space used (sstBackupSize): The disk space the account uses for the backup itself (disk space used under the <code>incoming</code> folder of the users chroot-home directory)
*#* Snapshot space used (sstIncrementSize): The disk space the account uses for the iterations (disk space under the <code>.snapshot</code> folder of the users chroot-home directory)
*# The file <code>etc/backupSize</code> of the accounts chroot (used by the Sepiola Online Backup client):
* Checks if the user and/or reseller must be notified that there is no more disk space left for the given account
** Checks if the notification flag was passed, if not no notification will be triggered
** Calculates the used disk space (backup and iterations) in percentage
** Reads the notification threshold value from the LDAP backed
** If the disk space used (in percentage) is bigger than the value retrieved from the LDAP backend start the [[stoney_cloud:_Notification_Architecture | notification]] process with
*** Product: Given account UID
*** Service: Backup
*** Problem: Quota
* Pod documentation:
<pre>
NAME
writeAccountSize.pl

DESCRIPTION
This Script gets quota information from filesystem, size of incoming and
snapshots directories, write the data to a file and the LDAP backend and
sends an e-mail message for each account that is over quota to users
e-mail address (from ldap directory) if notification flag is passed.

The configuration file for this script is stored in the backup-utils
configuration directory (/etc/backup-utils/) and is called
writeAccountSize.conf.

The script needs access to the quota program to get quota information.
The script needs ldap access to get users e-mail address and quota
information. The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

-C configfile
The configuration file.

-U uid
The user id.

-n notification
Start notification process if quota threshold is reached

-d debug
Turns the debug mode on.

-h help
This online help.

USAGE
writeAccountSize.pl -U uid [-C configuration file ] []-d debug] [-h
help] [-n]

CREATED
2009-04-16 michael.rhyner@stepping-stone.ch created

VERSION
2009-04-16 michael.rhyner@stepping-stone.ch created
2009-04-30 michael.rhyner@stepping-stone.ch changed position based quota
output parsing with correctly parsed elements
2009-06-15 michael.rhyner@stepping-stone.ch added over quota check and
sending e-mail
2009-06-16 michael.rhyner@stepping-stone.ch renamed script and make it
more general usable (e.g. for online backup, online storage, ...)
2009-06-17 michael.rhyner@stepping-stone.ch changed mail message to read
from a text file instead from configuration parameter
2009-06-18 michael.rhyner@stepping-stone.ch corrected wrong regex to
weed out the asterisk (*) in getQuotaSize
2009-06-19 michael.rhyner@stepping-stone.ch corrected wrong evaluation
success from subroutines and avoid message output when not in debug mode
2009-06-22 michael.rhyner@stepping-stone.ch getQuotaSize: return
immediately if no quota was set
2009-06-24 michael.rhyner@stepping-stone.ch alert when used certain
percentge of allowed space instead of more than allowed space
2009-06-26 michael.rhyner@stepping-stone.ch values are presented in
Gigabytes within notification message
2009-07-23 michael.rhyner@stepping-stone.ch corrected wrong syslog
severities for errors
2009-07-24 michael.rhyner@stepping-stone.ch made e-mail address
available within message body
2013-08-19 pat.klaey@stepping-stone.ch write quota values also to the
LDAP

INCORPORATED CODE
Incorporate code with use:

warnings;
strict;
Config::IniFiles;
Getopt::Std;
Sys::Syslog;
File::Basename;
Text::Template;
POSIX;
Notification;
PerlUtil::Logging;
PerlUtil::LDAPUtil;
</pre>

=== Configuration ===
/etc/backup-utils/writeAccountSize.conf
<pre>
[Global]
INCOMING_DIRECTORY = /incoming
ACCOUNT_SIZE_FILE = /etc/backupSize
SNAPSHOTS = 1

[Syslog]
SYSLOG = rsnapshot

[Directory]
LDAP_SERVER = ldaps://ldapm.tombstone.ch
LDAP_PORT = 636
LDAP_BIND_DN = cn=Manager,dc=stoney-cloud,dc=org
LDAP_BIND_PW = <password>
LDAP_BASE_DN = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
LDAP_PERSON_BASE = ou=people,dc=stoney-cloud,dc=org
LDAP_RESELLER_BASE = ou=reseller,ou=configuration,ou=backup,ou=services,dc=stoney-cloud,dc=org
LDAP_EMAIL_ATTRIBUTE = mail

[Notification]
EMAIL_SENDER = stepping stone GmbH Supprt <support@stepping-stone.ch>
EMAIL_ALERT_THRESHOLD = 85

Salutation_Default_de-CH = Liebe Kundin / Lieber Kunde
Salutation_m_de-CH = Sehr geehrter Herr
Salutation_f_de-CH = Sehr geehrte Frau
Salutation_Default_en-GB = Dear customer
Salutation_m_en-GB = Dear Mr.
Salutation_f_en-GB = Dear Mrs.
</pre>

=== Tests ===
/usr/libexec/backup-utils/writeAccountSize.pl -U 4000080 -d
<pre>
Debug modus was turned on

Debug sub checkUsersHomeDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersHomeDirectory: The $localUsersHomeDirectory /var/backup/080/4000080/home/4000080 exists

Debug sub checkUsersIncomingDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersIncomingDirectory: $localUsersIncomingDirectory: /incoming
Debug sub checkUsersIncomingDirectory: $localIncomingPath: /var/backup/080/4000080/home/4000080/incoming

Debug sub checkUsersIncomingDirectory: The $localIncomingPath /var/backup/080/4000080/home/4000080/incoming exists
Total Quota: 1048576 kilobytes
Total used Space: 0 kilobytes
Incoming Size: 0 kilobytes
Debug sub getSnapshotsSize: $localUsedQuota: 0
Debug sub getSnapshotsSize: $localSnapshotsSize: 0
Debug writeAccountSize: Working on /var/backup/080/4000080/etc/backupSize
Debug: wrote 1024 0 0 to /var/backup/080/4000080/etc/backupSize
DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstBackupSize => 0

DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstIncrementSize => 0

Alert Threshold: 85 %
Calculated value: 0
</pre>

Now write some data (200 megaytes in this example) into the users incoming directory and then execute the script again:
dd if=/dev/zero of=/var/backup/080/4000080/home/4000080/incoming/test.zeros bs=1024k count=200
chown 4000080:4000080 /var/backup/080/4000080/home/4000080/incoming/test.zeros
/usr/libexec/backup-utils/writeAccountSize.pl -U 4000080 -d

<pre>
Debug modus was turned on

Debug sub checkUsersHomeDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersHomeDirectory: The $localUsersHomeDirectory /var/backup/080/4000080/home/4000080 exists

Debug sub checkUsersIncomingDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersIncomingDirectory: $localUsersIncomingDirectory: /incoming
Debug sub checkUsersIncomingDirectory: $localIncomingPath: /var/backup/080/4000080/home/4000080/incoming

Debug sub checkUsersIncomingDirectory: The $localIncomingPath /var/backup/080/4000080/home/4000080/incoming exists
Total Quota: 1048576 kilobytes
Total used Space: 204800 kilobytes
Incoming Size: 204800 kilobytes
Debug sub getSnapshotsSize: $localUsedQuota: 204800
Debug sub getSnapshotsSize: $localSnapshotsSize: 0
Debug writeAccountSize: Working on /var/backup/080/4000080/etc/backupSize
Debug: wrote 1024 200 0 to /var/backup/080/4000080/etc/backupSize
DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstBackupSize => 209715200

DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstIncrementSize => 0

Alert Threshold: 85 %
Calculated value: 19.53125
</pre>
Everything seems to be working fine!

== snapshot.pl ==
This script is installed to <code>/usr/libexec/backup-utils/snapshot.pl</code> by the <code>sys-apps/sst-backup-utils</code> package and does the following:
* Read interval parameter value passed
** The interval parameter value can be daily, weekly, monthly (or yearly)
* Find all backup active accounts for which the rsnapshot command must be executed (depending on the given interval)
** Filter to find these accounts: <code>(&(sstBackupInterval<INTERVAL>=*)(sstIsActive=TRUE))</code> for example for the daily rsnapshot the filter is <code>(&(sstBackupIntervalDaily=*)(sstIsActive=TRUE))</code>
*** In other words this means: Get me all acounts that have for <code>sstBackupInterval<INTERVAL></code> a value defined AND <code>sstIsActive</code> is set to "TRUE"
* According to the interval given and the account UID calculate the rsnapshot command for all these accounts
** For example
*** Account UID: 4000000
*** Interval: daily
*** Resulting rsnapshot command: /usr/bin/nice -n 19 /usr/bin/rsnapshot -c /etc/rsnapshot/rsnapshot.conf.4000000 daily (if you use the [[#snapshot.pl_Configuration | configuration]] below)
* Execute all these commands
** Use controlled parallel execution, you can specify how many commands can be executed in parallel (see [[#snapshot.pl_Configuration | configuration]] below)
* Pod documentation:
<pre>
NAME
snapshot.pl

DESCRIPTION
This script gets all active online backup accounts from the LDAP backend
for which the rsnapshot process for the given interval must be executed.
According to these accounts and the given interval, the commands to be
executed are generated and finally executed. The commands can be
executed in parallel, however there is a limit defined in the
configuration file which limits the amount of parallel running
processes.

USAGE
./snapshot.pl --interval interval [--debug] [--help]

OPTIONS
--interval/-i interval
Specifies the rsnapshot interval (can be hourly, daily, weekly,
monthly or yearly)

--debug/-d
Turns on debug mode

--help/-h
Shows this help

CREATED
2012-03-19 pat.klaey@stepping-stone.ch created

VERSION
2012-03-19 pat.klaey@stepping-stone.ch created

INCORPORATED CODE
Incorporated code with use:

warnings;
strict;
Getopt::Long;
Sys::Syslog;
PerlUtil::Logging;
PerlUtil::LDAPUtil;
File::Basename;
Parallel::ForkManager;
Time::Stopwatch;
</pre>

=== Configuration ===
There are two things to do in this step:
* Configure the rsnapshot root directory
* Configure the snapshot.pl script itself

==== rsnaphot configuration directory ====
The users individual rsnapshot configurations are stored under <code>/etc/rsnapshot</code>. Please make sure, that the directory exists:
ls -al /etc | grep rsnapshot

drwx------ 2 root root 64 30. Aug 20:20 rsnapshot

If not, create it:
mkdir /etc/rsnapshot
chmod 700 /etc/rsnapshot

==== snapshot.pl Configuration ====
The snapshot.pl script is responsible for the execution of rsnapshot according to the users settings.
/etc/backup-utils/snapshot.conf
<pre>
[General]
MaxParallelProcesses = 5
Rsnapshot_command = /usr/bin/nice -n 19 /usr/bin/rsnapshot -c /etc/rsnapshot/rsnapshot.conf.%uid% %interval%

[LDAP]
Host = ldaps://ldapm.tombstone.ch
Port = 636
User = cn=Manager,dc=stoney-cloud,dc=org
Password = <Password>
CA_Path = /etc/ssl/certs
Accounts_Base = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
</pre>

Legend: At runtime the following placeholders are replaced as follows
* '''%uid%''': The backup account and login uid as a numeric number. For example: 4000205.
* '''%interval%''': The backup level to be executed. Possible values are hourly, daily, weekly, monthly and yearly.

=== Tests ===
Before adding the necessary cronjob entries, we need to make sure, that we've configured the snapshot.pl script correctly:
/usr/libexec/backup-utils/snapshot.pl --interval daily -d

If everything worked as planned, you should receive feedback looking roughly like:
<pre>
INFO: Starting rsnapshot for interval daily with maximum 5 parallel processes

INFO: Executing snapshot for 4000080

INFO: Executing snapshot for 4000079

INFO: Snapshot process for 4000079 finished in 0.18 seconds with status 0

INFO: Snapshot process for 4000080 finished in 0.19 seconds with status 0

INFO: rsnapshot for all backups done. Took 0.24 seconds
</pre>

Just to make sure, that everything did work out fine, execute <code>writeAccountSize.pl</code> again:
/usr/libexec/backup-utils/writeAccountSize.pl -U 4000080 -d
<pre>
Debug modus was turned on

Debug sub checkUsersHomeDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersHomeDirectory: The $localUsersHomeDirectory /var/backup/080/4000080/home/4000080 exists

Debug sub checkUsersIncomingDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersIncomingDirectory: $localUsersIncomingDirectory: /incoming
Debug sub checkUsersIncomingDirectory: $localIncomingPath: /var/backup/080/4000080/home/4000080/incoming

Debug sub checkUsersIncomingDirectory: The $localIncomingPath /var/backup/080/4000080/home/4000080/incoming exists
Total Quota: 1048576 kilobytes
Total used Space: 409600 kilobytes
Incoming Size: 204800 kilobytes
Debug sub getSnapshotsSize: $localUsedQuota: 409600
Debug sub getSnapshotsSize: $localSnapshotsSize: 204800
Debug writeAccountSize: Working on /var/backup/080/4000080/etc/backupSize
Debug: wrote 1024 200 200 to /var/backup/080/4000080/etc/backupSize
DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstBackupSize => 209715200

DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstIncrementSize => 209715200

Alert Threshold: 85 %
Calculated value: 39.0625
</pre>

As you can see, the total used space has risen to 39.0625.

=== Cronjobs ===
After making sure, that everything worked as planned, you can update your crontab entry:
crontab -e
<pre>
...
# Rsnapshot for all users
30 22 * * * /usr/libexec/backup-utils/snapshot.pl --interval daily
15 22 * * sun /usr/libexec/backup-utils/snapshot.pl --interval weekly
00 22 1 * * /usr/libexec/backup-utils/snapshot.pl --interval monthly
...
</pre>

* TBD: Maybe this is not optimal if there is a lot of data to rotate. In this case, it might be that for example weekly and daily snapshot both run at the same time what might lead to strange results.
* Workarounds:
** Simple/short version: Instead one could create another wrapper script which is called everyday and does some simple logic:
** Is today the first day of a month?
*** Yes: Is today sunday?
**** Yes: Execute monthly then weekly then daily rsnapshots using the snapshot.pl script (but wait for each interval to finish before starting the next)
**** No: Execute monthly then daily rsnapshots using the snapshot.pl script (but wait for monthly interval to finish before starting the daily)
*** No: Is today sunday?
**** Yes: Execute weekly then daily rsnapshots using the snapshot.pl script (but wait for weekly interval to finish before starting the daily)
**** No: Execute daily rsnapshots using the snapshot.pl script
** Complex/long version: Adapt the snapshot.pl script and call it every day without interval parameter. The script does the logic described above.
This avoids the above mentioned collision

(Complex) / short version: rule via cronjobs:
<pre>
# Rsnapshot for all users
30 22 * * 1-6 [ $( date +\%d ) -gt 1 ] && /usr/libexec/backup-utils/snapshot.pl --interval daily
15 22 * * 7 [ $( date +\%d ) -gt 1 ] && /usr/libexec/backup-utils/snapshot.pl --interval weekly && /usr/libexec/backup-utils/snapshot.pl --interval daily
00 22 1 * * /usr/libexec/backup-utils/snapshot.pl --interval monthly && /usr/libexec/backup-utils/snapshot.pl --interval weekly && /usr/libexec/backup-utils/snapshot.pl --interval daily
...
</pre>

== scheduleWarning.pl ==
This script is installed to <code>/usr/libexec/backup-utils/scheduleWarning.pl</code> by the <code>sys-apps/sst-backup-utils</code> package and does the following:
* The basic task of this script is simple: For the given account
** Check if the planned backups were started
*** If not, start the [[stoney_cloud:_Notification_Architecture | notification]] process with
**** Product: Given account UID
**** Service: Backup
**** Problem: Schedule
** Check if the planned backups finished successfully
*** If not, start the [[stoney_cloud:_Notification_Architecture | notification]] process with
**** Product: Given account UID
**** Service: Backup
**** Problem: Unsuccessful

As the backup clients distributed by stepping stone GmbH upload metadata XML before (scheduling information and start time) and after (end time and backup status) the actual backup, the scheduleWarning.pl script is able to verify whether or not a planned backup has been executed and whether or not the backup was successful.

* Pod documentation
<pre>
NAME
scheduleWarning.pl

DESCRIPTION
This script tests whether a planed backup was successful or not. There
are two different typs of failure.

1. The Backup did not start
The first type of error is that a backup is scheduled for YYYY-MM-DD
at HH:MM, but the backup don't start at this specified time. A
possible reason could be that the computer was shut down.

2.The backup was not successful
The second type of error is that a backup started as scheduled but
did not finish successfully. There are different reasons for this
error.

If a backup wasn't successful the script checks which type of error
occured. It reads the XML files which are stored on the server and
compares the given information. If the error is detected, the script
stats the norification process with the information of the error.

If a user has more than one computer backed-up, the script tests one
computer after the other. The mail(s) sent by the programm also
contain(s) the information which computer is affected.

OPTION
-U uid
The -U option is required to run the script, it indicates for which
uid the script is executed.

USAGE
scheduleWarning.pl [-U user]

CREATED
2010-04-14 created Pat Kläy <pat.klaey@stepping-stone.ch>

VERSION
2010-04-14 v0.01, created pkl
2010-08-24 v0.02, modified pkl
New using Net::SMTP::TLS to send mails

2013-09-13 v0.03, modified pat.klaey@stepping-stone.ch
Changes to use the script with the new backup infrastructure (read
more information from LDAP, use Notification lib to send mails)

USES
strict;
warnings;
XML::Simple;
Config::IniFiles;
XML::Validator::Schema;
Date::Calc qw(:all);
Date::Manip;
Schedule::Cron::Events;
DateTime::Format::Strptime;
Sys::Syslog;
XML::SAX::ParserFactory;
Getopt::Std;
MIME::Base64;
Authen::SASL;
Net::LDAPS;
Net::SMTP::TLS;
Cwd 'abs_path';
PerlUtil::Logging;
PerlUtil::LDAPUtil;
</pre>

=== Configuration ===
/etc/backup-utils/scheduleWarning.conf
<pre>
[Backup]
CHROOT_DIRECTORY = /var/backup/%lastthree%/%user%

[XML]
SCHEDULE_FILE = %homeDirectory%/incoming/%computerName%/.sepiola_backup/scheduler.xml
SCHEDULE_XSD = /etc/backup-utils/schema/scheduler_schema.xsd
BACKUP_ENDED_FILE = %homeDirectory%/incoming/%computerName%/.sepiola_backup/backupEnded.xml
BACKUP_ENDED_XSD = /etc/backup-utils/schema/backupended_schema.xsd
BACKUP_STARTED_FILE = %homeDirectory%/incoming/%computerName%/.sepiola_backup/backupStarted.xml
BACKUP_STARTED_XSD = /etc/backup-utils/schema/backupstarted_schema.xsd

[TEMPLATE]
Salutation_Default_de-CH = Liebe Kundin / Lieber Kunde
Salutation_m_de-CH = Sehr geehrter Herr
Salutation_f_de-CH = Sehr geehrte Frau
Salutation_Default_en-GB = Dear customer
Salutation_m_en-GB = Dear Mr.
Salutation_f_en-GB = Dear Mrs.

[LDAP]

SERVER = ldaps://ldapm.tombstone.ch
PORT = 636
DEBUG = 1

ADMIN_DN = cn=Manager,dc=stoney-cloud,dc=org
ADMIN_PASSWORD = <Password>

BACKUP_BASE = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
PEOPLE_BASE = ou=people,dc=stoney-cloud,dc=org
RESELLER_BASE = ou=reseller,ou=configuration,ou=backup,ou=services,dc=stoney-cloud,dc=org
SCOPE = sub

</pre>

== checkBackups.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeDate.pl</code> by the <code>sys-apps/sst-backup-utils</code> package. It is a wrapper around the above mentioned <code>writeAccountSize.pl</code> and <code>scheduleWarning.pl</code> scripts (if you configure it accordingly).
* As mentioned the script is a wrapper for calling the quota and scheduler information scripts:
** It gets all active backup accounts from the LDAP directory
** According to the CLI parameters passed it calles for all these accounts:
*** The quota checking script (this script can be defined in the configuration file, see [[stoney_backup:_Server_set-up#Configuration_6 | configuration]] section below)
*** The scheduler checking script (this script can be defined in the configuration file, see [[stoney_backup:_Server_set-up#Configuration_6 | configuration]] section below)
* Pod documentation:
<pre>
NAME
checkBackups.pl

DESCRIPTION
This script processes all active backup accounts and checks (according
to the command line options) the quota and/or the scheduled backups for
the given accounts.

The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

OPTIONS
--schedule/-s
Checks schedule information by calling the defined script

--quota/-s
Checks the quota values by calling the defined script

--notify/-n
Passes the notify flag to the called scripts

USAGE
./checkBackups.pl [--quota] [--schedule] [--notify]

./checkBackups.pl --quota
Checks and writes the quota for all active backup accounts. The user
and/or reseller will NOT be informed if any quota threshold is
reached

./checkBackups.pl --quota --notify
Checks and writes the quota for all active backup accounts. The user
and/or reseller will be informed if any quota threshold is reached.

./checkBackups.pl --schedule
Checkes all active backup account if the scheduled backup was
executed and successful. The --schedule option will allways trigger
a notification mail to the user and/or reseller.

./checkBackups.pl --schedule --quota
Checks both, quota and schedule, for all active backup accounts.
Only schedule will trigger notification mails.

./checkBackups.pl --schedule --quota --notify
Checks both, quota and schedule, for all active backup accounts.
Both, quota and schedule, will trigger notification mails.

CREATED
2013-09-17 pat.klaey@stepping-stone.ch created

VERSION
2013-09-17 pat.klaey@stepping-stone.ch created
2013-11-19 pat.klaey@stepping-stone.ch Added options to be able to check
quota, schedule or both in one run

INCORPORATED CODE
Incorporated code with use:

warnings;
strict;
Getopt::Long;
Sys::Syslog;
Cwd 'abs_path';
File::Basename;
PerlUtil::LDAPUtil;
PerlUtil::Logging;
</pre>

=== Configuration ===
In the configuration you have to define two simple things:
# Which script to call for quota checks and scheduler checks
# How to access the LDAP backend
/etc/backup-utils/checkBackups.conf
<pre>
[Scripts]
CheckQuotaScript = /usr/libexec/backup-utils/writeAccountSize.pl
CheckScheduleScript = /usr/libexec/backup-utils/scheduleWarning.pl

[LDAP]
Server = ldaps://ldapm.tombstone.ch
Port = 636
Username = cn=Manager,dc=stoney-cloud,dc=org
Password = <PASSWORD>
AccountBase = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
</pre>

==== Cronjobs ====
As you can pass the notification flag to the scripts, you can call the quota script say all 10 minutes. This makes sense if followed the configuration section, as the writeAccountSize.pl script writes the quota values to the LDAP backend which will then be visible in the selfcare webinterface. Like that you have a more or less up to date quota representation in the selfcare webinterface. On the other side, you don't want to send notification mails to the user every 10 minutes. It might be enough to send them once a day, so the cronjobs may look like:
<pre>
# Check backups
15 12 * * * /usr/libexec/backup-utils/checkBackups.pl --schedule --quota --notify

# Write quota values every 10 minutes
*/10 * * * * /usr/libexec/backup-utils/checkBackups.pl --quota
</pre>

== ResellerBackupBilling.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeDate.pl</code> by the <code>sys-apps/sst-backup-utils</code> package. The pod documentation says all what needs to be said about this script.
* Pod documentation
<pre>
NAME
ResellerBackupBilling.pl

DESCRIPTION
This script processes the reseller with the passed UID and creates a
very simplistic backup-billing overview which then is sent to the
address specified in the configuration file. The billing overview
contains all backup accounts which belong to the given reseller as well
as their quota. According to the billing plan specified in the
configuration file, the script also calculates the price for each backup
account.

The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

OPTIONS
--reseller/-r UID
Process the reseller with this UID

--debug/-d
Turn on debug mode

--help/-h
Display this help

USAGE
./ResellerBackupBilling.pl --reseller UID [--debug] [--help]

./ResellerBackupBilling.pl --reseller 2000000
This processes the reseller with the UID 200000 and sends the
billing overview to the address specified in the configuration file

CREATED
2014-01-24 pat.klaey@stepping-stone.ch created

VERSION
2014-01-24 pat.klaey@stepping-stone.ch created

INCORPORATED CODE
Incorporated code with use:

warnings;
strict;
Getopt::Long;
PerlUtil::LDAPUtil;
PerlUtil::Logging;
PerlUtil::Mail;
Number::Format;
File::Basename;
Cwd 'abs_path';
</pre>
=== Configuration ===
You have to configure basically three things:
# How to access the LDAP directory (similar to the other backup-util scripts)
# Define a pricing schema
#* Define a base price for an account
#* Define a GB price
#* The total price for each account will finall be: <code>base price + ( quota in GB * GB price )</code>
# How to send the mail
#* You need to enter a valid (outgoing) mail server and corresponding port
#* User and password to authenticate on the mail server
#* A valid recipient (typically the company’s backoffice address) and sender

/etc/backup-utils/ResellerBackupBilling.conf
<pre>
[LDAP]
Server = ldaps://ldapm.tombstone.ch
Port = 636
Username = cn=Manager,dc=stoney-cloud,dc=org
Password = <Password>
AccountBase = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
CustomerBase = ou=customers,dc=stoney-cloud,dc=org
ResellerBase = ou=reseller,dc=stoney-cloud,dc=org

[Pricing]
AccountBasePrice = 5.00
AccountGBPrice = 0.50

[Mail]
Server = <Mail-Server>
Port = 587
Username = <Sender-Email-Address>
Password = <Password>
To = <Backoffice>
From = Billing Script <E-Mail-Address>
</pre>

== writeDate.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeDate.pl</code> by the <code>sys-apps/sst-backup-utils</code> package. This is a very simple script, it simply writes the current date and time to a file on the backup server before the rsnapshots rotates the backup. This date is used by the Sepiola Online Backup Client to display the iterations and their dates.
* Pod documentation:
<pre>
NAME
writeDate.pl

DESCRIPTION
This script writes the current date and time into the file for each
backup before the rsnapshots rotates the backup. This information is
used by the Sepiola Online Backup Client.

The configuration file for this script is stored under
/etc/backup-utils/writeDate.conf

The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

-C configfile
The configuration file.

-U uid
The user id.

-d debug
Turns the debug mode on.

-h help
This online help.

USAGE
writeDate.pl [-C configuration_file] [-U uid] [-d debug] [-h help]

CREATED
2007-09-16 michael.eichenberger@stepping-stone.ch created

VERSION
2013-09-01 michael.eichenberger@stepping-stone.ch updated to reflect
changes in the new backup environment

2007-09-16 michael.eichenberger@stepping-stone.ch created

INCORPORATED CODE
Incorporate code with use:

warnings;
strict;
Config::IniFiles;
Getopt::Std;
Sys::Syslog;
</pre>

=== Configuration ===
/etc/backup-utils/writeDate.conf
<pre>
[Global]
BACKUP_DIRECTORY = /incoming
BACKUP_BACKUP_TIME_FILE = /.sepiola_backup/backupTime

[Syslog]
SYSLOG = rsnapshot
</pre>

== rsnapshot wrapper bash scripts ==
There are two rsnapshot wrapper scripts (these are bash scripts), they are installed by the <code>sys-apps/sst-backup-utils</code> package:
* <code>/usr/libexec/backup-utils/rsnapshotPreExecWrapper.sh</code>
** This script is executed before the rsnapshot process and simply calls the [[stoney_backup:_Server_set-up#writeDate.pl | writeDat.pl ]] script.
* <code>/usr/libexec/backup-utils/rsnapshotPostExecWrapper.sh</code>
** This script is executed after the rsnapshot process and simply calls the [[stoney_backup:_Server_set-up#writeAccountSize.pl | writeAccountSize.pl ]] script.

'''Note:''' These scripts do not need any configuration.

= Links =
* [http://www.openldap.org/ OpenLDAP], an open source implementation of the Lightweight Directory Access Protocol.
* [http://arthurdejong.org/nss-pam-ldapd/ nss-pam-ldapd], a Name Service Switch (NSS) module that allows your LDAP server to provide user account, group, host name, alias, netgroup, and basically any other information that you would normally get from /etc flat files or NIS.
* [http://www.gentoo.org/doc/de/ldap-howto.xml Gentoo Leitfaden zur OpenLDAP Authentifikation].
* [http://wiki.gentoo.org/wiki/Centralized_authentication_using_OpenLDAP Centralized authentication using OpenLDAP].
* [https://code.google.com/p/openssh-lpk/source/browse/trunk/schemas/openssh-lpk_openldap.schema openssh-lpk_openldap.schema] OpenSSH LDAP Public Keys.
* [http://sourceforge.net/projects/linuxquota/ linuxquota] Linux DiskQuota.
* [http://www.rsnapshot.org/ rsnapshot], a remote filesystem snapshot utility, based on rsync.
* [http://olivier.sessink.nl/jailkit/ Jailkit], set of utilities to limit user accounts to specific files using chroot() and or specific commands. Also includes a tool to build a chroot environment.
* [http://www.busybox.net/ Busybox] BusyBox combines tiny versions of many common UNIX utilities into a single small executable. Useful to reduce the number of files (and thus the complexity) when building a chroot.

[[Category:stoney backup]]

stoney backup: prov-backup-rsnapshot

2014-06-19T08:09:35Z

Chrigu: /* Test the daemon */

= Overview =
This pages contains all necessary information one needs to know about the prov-backup-rsnapshot daemon.
@PAT: What's the purpose of the ''prov-backup-rsnapshot daemon''? Please write a short introduction. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 10:02, 19 June 2014 (CEST)

= Configuration =
(Note: Comments starting with /* are not in the configuration file, they are only in the wiki to add some additional information)

<pre>
# Copyright (C) 2013 stepping stone GmbH
# Switzerland
# http://www.stepping-stone.ch
# support@stepping-stone.ch
#
# Authors:
# Pat Kläy <pat.klaey@stepping-stone.ch>
#
# Licensed under the EUPL, Version 1.1.
#
# You may not use this work except in compliance with the
# Licence.
# You may obtain a copy of the Licence at:
#
# http://www.osor.eu/eupl
#
# Unless required by applicable law or agreed to in
# writing, software distributed under the Licence is
# distributed on an "AS IS" basis,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
# express or implied.
# See the Licence for the specific language governing
# permissions and limitations under the Licence.
#

/* If you want, you can override the log information from the global configuration file this might be useful for debugging */
[Global]
# If true the script logs every information to the log-file.
LOG_DEBUG = 1

# If true the script logs additional information to the log-file.
LOG_INFO = 1

#If true the script logs warnings to the log-file.
LOG_WARNING = 1

#If true the script logs errors to the log-file.
LOG_ERR = 1

/* Specify the hosts fully qualified domain name. This name will be used to perform some checks and also appear in the information and error mails */
ENVIRONMENT = <FQDN>

[Database]
BACKEND = LDAP
SERVER = ldaps://ldapm.tombstone.org
PORT = 636
ADMIN_USER = cn=Manager,dc=stoney-cloud,dc=org
ADMIN_PASSWORD = <PASSWORD>
SERVICE_SUBTREE = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
COOKIE_FILE = /etc/Provisioning/Backup/rsnapshot.cookie
DEFAULT_COOKIE = rid=001,csn=
SEARCH_FILTER = (&(entryCSN>=%entryCSN%)(sstProvisioningState=0))

/* Specifies the service itself. As it is the prov-backup-rsnapshot module, the SERVICE is "Backup" and the TYPE is "Rsnapshot".
* The MODUS is as usual selfcare and the TRANSPORTAPI is LocalCLI. This is because the daemon is running on the same host as the
* backup accounts are provisioned and the commands can be executed on this host using the cli.
* For more information about MODUS and TRANSPORTAPI see https://int.stepping-stone.ch/wiki/provisioning.pl#Service_Konfiguration
*/
[Service]
MODUS = selfcare
TRANSPORTAPI = LocalCLI
SERVICE = Backup
TYPE = Rsnapshot

SYSLOG = prov-backup-rsnapshot

/* For the TRANSPORTAPI LocalCLI there is no gateway required because there is no connection to establish. So set HOST, USER and
* DSA_FILE to whatever you want. Don't leave it blank, otherwise the provisioning daemon would log some error messages saying
* these attributes are empty
*/
[Gateway]
HOST = localhost
USER = provisioning
DSA_FILE = none

/* Information about the backup itself (how to setup everything). Note that the %uid% int the RSNAPSHOT_CONFIG_FILE parameter will
* be replaced by the accounts UID. The script CREATE_CHROOT_CMD was installed with the prov-backup-rsnapshot module, so do not
* change this parameter. The quota parameters (SET_QUOTA_CMD, MOUNTPOINT, QUOTA_FILE, PROJECTS_FILE and PROJID_FILE) represent
* the quota setup as described on http://wiki.stoney-cloud.org/index.php/stoney_backup:_Server_set-up#Quota. If you followed this
* manual, you can copy-paste them into your configuration file, otherwise adapt them according to your quota setup.
*/
[Backup]
RSNAPSHOT_CONFIG_FILE = /etc/rsnapshot/rsnapshot.conf.%uid%
SET_QUOTA_CMD = /usr/sbin/xfs_quota
CREATE_CHROOT_CMD = /usr/libexec/createBackupDirectory.sh
MOUNTPOINT = /var
QUOTA_FILE = /etc/backupSize
PROJECTS_FILE = /etc/projects
PROJID_FILE = /etc/projid
</pre>

= Communication with LDAP =
The daemon "communicates" with the LDAP to let other processes know its current state. The important attributes therefore are '''sstProvisioningMode''' and '''sstProvisioningState''' in the given Backup-Account entry. The sequence is defined for adding, modifying or deleting an entry. The preconditions for all three modi are:
* sstProvisioningMode is set to add, modify or delete
* sstProvisioningState is set to 0
* sstProvisioningDate is set to 0 or the current date (format: YYYYMMDD)

== Add ==
=== Precondition ===
<source lang="ldif">
...
sstProvisioningMode: add
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: adding
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: added
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

== Modify ==
=== Precondition ===
<source lang="ldif">
...
sstProvisioningMode: modify
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: modifying
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon has finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: modified
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

== Delete ==
=== Precondition ===
<source lang="ldif">
...
sstIsActive: FALSE
sstProvisioningMode: delete
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>

=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: deleting
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: deleted
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

= Source Code =
The source code is located in our GitHub Repository:

https://github.com/stepping-stone/prov-backup-rsnapshot

== Exit Codes ==
The following list defines the return codes and their meaning for the ...:
<pre>
use constant
{
SUCCESS => 0,
UNDEFINED_ERROR => 1,
USER_NOT_PRESENT_IN_BACKEND => 2,
PERL_VERSION_NOT_STATISFIED => 3,
CANNOT_CHECK_HOME_DIR_PRESENCE => 4,
CANNOT_CREATE_HOME_DIR => 5,
CANNOT_SET_QUOTA => 6,
CANNOT_CREATE_RSNAPSHOT_CONFIGURATION => 7,
};
</pre>

= Testing =
== Requirements ==
A working test server set up following the [[stoney_backup:_Server_set-up#prov-backup-rsnapshot | stoney backup: Server set-up]] guide.

== Test the daemon ==
* The daemon is running on the Backup-Server VM
** Open a terminal and login to the Backup-Server VM
** <pre>tail -f /var/log/syslog/provisioning.log</pre>
* Open a second terminal and login to the Backup-Server VM
** Make sure the directory /root/data exists, if not create it
** Create an online backup account by executing the test script:
** <pre>/usr/libexec/createBackupDirectory.sh --uid 3724300</pre>
** The test script currently supports the following options:
*** --uid <UID>: Mandatory option, the backup accounts uid
*** --reseller <UID>: Optional, sets sstBelongsToResellerUID (default 4000000)
*** --customer <UID>: Optional, sets sstBelongsToCustomerUID (default 4000001)
*** --people <UID>: Optional, sets sstBelongsToPersonUID (default 4000002)
*** --givenname <Name>: Optional, sets the givenname attribute (default "Givenname")
*** --surname <Name>: Optional, sets the sn attribute (defualt "Surname")
** Load the generated LDIF (you find them under /root/data) step by step into the LDAP and observe what the deamon is doing in the first terminal:
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/01_add_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/02_modify_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/03_delete_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/04_remove_3724300.ldif</pre>

@PAT: What are the expected results of this test, how can one verify if it is working correctly? --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 10:09, 19 June 2014 (CEST)

= Links =

[[Category:stoney backup]][[Category:Provisioning Modules]]

stoney backup: prov-backup-rsnapshot

2014-06-19T08:07:57Z

Chrigu: /* Test the daemon */

= Overview =
This pages contains all necessary information one needs to know about the prov-backup-rsnapshot daemon.
@PAT: What's the purpose of the ''prov-backup-rsnapshot daemon''? Please write a short introduction. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 10:02, 19 June 2014 (CEST)

= Configuration =
(Note: Comments starting with /* are not in the configuration file, they are only in the wiki to add some additional information)

<pre>
# Copyright (C) 2013 stepping stone GmbH
# Switzerland
# http://www.stepping-stone.ch
# support@stepping-stone.ch
#
# Authors:
# Pat Kläy <pat.klaey@stepping-stone.ch>
#
# Licensed under the EUPL, Version 1.1.
#
# You may not use this work except in compliance with the
# Licence.
# You may obtain a copy of the Licence at:
#
# http://www.osor.eu/eupl
#
# Unless required by applicable law or agreed to in
# writing, software distributed under the Licence is
# distributed on an "AS IS" basis,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
# express or implied.
# See the Licence for the specific language governing
# permissions and limitations under the Licence.
#

/* If you want, you can override the log information from the global configuration file this might be useful for debugging */
[Global]
# If true the script logs every information to the log-file.
LOG_DEBUG = 1

# If true the script logs additional information to the log-file.
LOG_INFO = 1

#If true the script logs warnings to the log-file.
LOG_WARNING = 1

#If true the script logs errors to the log-file.
LOG_ERR = 1

/* Specify the hosts fully qualified domain name. This name will be used to perform some checks and also appear in the information and error mails */
ENVIRONMENT = <FQDN>

[Database]
BACKEND = LDAP
SERVER = ldaps://ldapm.tombstone.org
PORT = 636
ADMIN_USER = cn=Manager,dc=stoney-cloud,dc=org
ADMIN_PASSWORD = <PASSWORD>
SERVICE_SUBTREE = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
COOKIE_FILE = /etc/Provisioning/Backup/rsnapshot.cookie
DEFAULT_COOKIE = rid=001,csn=
SEARCH_FILTER = (&(entryCSN>=%entryCSN%)(sstProvisioningState=0))

/* Specifies the service itself. As it is the prov-backup-rsnapshot module, the SERVICE is "Backup" and the TYPE is "Rsnapshot".
* The MODUS is as usual selfcare and the TRANSPORTAPI is LocalCLI. This is because the daemon is running on the same host as the
* backup accounts are provisioned and the commands can be executed on this host using the cli.
* For more information about MODUS and TRANSPORTAPI see https://int.stepping-stone.ch/wiki/provisioning.pl#Service_Konfiguration
*/
[Service]
MODUS = selfcare
TRANSPORTAPI = LocalCLI
SERVICE = Backup
TYPE = Rsnapshot

SYSLOG = prov-backup-rsnapshot

/* For the TRANSPORTAPI LocalCLI there is no gateway required because there is no connection to establish. So set HOST, USER and
* DSA_FILE to whatever you want. Don't leave it blank, otherwise the provisioning daemon would log some error messages saying
* these attributes are empty
*/
[Gateway]
HOST = localhost
USER = provisioning
DSA_FILE = none

/* Information about the backup itself (how to setup everything). Note that the %uid% int the RSNAPSHOT_CONFIG_FILE parameter will
* be replaced by the accounts UID. The script CREATE_CHROOT_CMD was installed with the prov-backup-rsnapshot module, so do not
* change this parameter. The quota parameters (SET_QUOTA_CMD, MOUNTPOINT, QUOTA_FILE, PROJECTS_FILE and PROJID_FILE) represent
* the quota setup as described on http://wiki.stoney-cloud.org/index.php/stoney_backup:_Server_set-up#Quota. If you followed this
* manual, you can copy-paste them into your configuration file, otherwise adapt them according to your quota setup.
*/
[Backup]
RSNAPSHOT_CONFIG_FILE = /etc/rsnapshot/rsnapshot.conf.%uid%
SET_QUOTA_CMD = /usr/sbin/xfs_quota
CREATE_CHROOT_CMD = /usr/libexec/createBackupDirectory.sh
MOUNTPOINT = /var
QUOTA_FILE = /etc/backupSize
PROJECTS_FILE = /etc/projects
PROJID_FILE = /etc/projid
</pre>

= Communication with LDAP =
The daemon "communicates" with the LDAP to let other processes know its current state. The important attributes therefore are '''sstProvisioningMode''' and '''sstProvisioningState''' in the given Backup-Account entry. The sequence is defined for adding, modifying or deleting an entry. The preconditions for all three modi are:
* sstProvisioningMode is set to add, modify or delete
* sstProvisioningState is set to 0
* sstProvisioningDate is set to 0 or the current date (format: YYYYMMDD)

== Add ==
=== Precondition ===
<source lang="ldif">
...
sstProvisioningMode: add
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: adding
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: added
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

== Modify ==
=== Precondition ===
<source lang="ldif">
...
sstProvisioningMode: modify
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: modifying
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon has finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: modified
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

== Delete ==
=== Precondition ===
<source lang="ldif">
...
sstIsActive: FALSE
sstProvisioningMode: delete
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>

=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: deleting
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: deleted
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

= Source Code =
The source code is located in our GitHub Repository:

https://github.com/stepping-stone/prov-backup-rsnapshot

== Exit Codes ==
The following list defines the return codes and their meaning for the ...:
<pre>
use constant
{
SUCCESS => 0,
UNDEFINED_ERROR => 1,
USER_NOT_PRESENT_IN_BACKEND => 2,
PERL_VERSION_NOT_STATISFIED => 3,
CANNOT_CHECK_HOME_DIR_PRESENCE => 4,
CANNOT_CREATE_HOME_DIR => 5,
CANNOT_SET_QUOTA => 6,
CANNOT_CREATE_RSNAPSHOT_CONFIGURATION => 7,
};
</pre>

= Testing =
== Requirements ==
A working test server set up following the [[stoney_backup:_Server_set-up#prov-backup-rsnapshot | stoney backup: Server set-up]] guide.

== Test the daemon ==
* The daemon is running on the Backup-Server VM
** Open a terminal and login to the Backup-Server VM
** <pre>tail -f /var/log/syslog/provisioning.log</pre>
* Open a second terminal and login to the Backup-Server VM
** Make sure the directory /root/data exists, if not create it
** Create an online backup account by executing the test script:
** <pre>/usr/libexec/createBackupDirectory.sh --uid 3724300</pre>
** The test script currently supports the following options:
*** --uid <UID>: Mandatory option, the backup accounts uid
*** --reseller <UID>: Optional, sets sstBelongsToResellerUID (default 4000000)
*** --customer <UID>: Optional, sets sstBelongsToCustomerUID (default 4000001)
*** --people <UID>: Optional, sets sstBelongsToPersonUID (default 4000002)
*** --givenname <Name>: Optional, sets the givenname attribute (default "Givenname")
*** --surname <Name>: Optional, sets the sn attribute (defualt "Surname")
** Load the generated LDIF (you find them under /root/data) step by step into the LDAP and observe what the deamon is doing in the first terminal:
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/01_add_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/02_modify_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/03_delete_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/04_remove_3724300.ldif</pre>

= Links =

[[Category:stoney backup]][[Category:Provisioning Modules]]

stoney backup: prov-backup-rsnapshot

2014-06-19T08:02:05Z

Chrigu: /* Overview */

= Overview =
This pages contains all necessary information one needs to know about the prov-backup-rsnapshot daemon.
@PAT: What's the purpose of the ''prov-backup-rsnapshot daemon''? Please write a short introduction. --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 10:02, 19 June 2014 (CEST)

= Configuration =
(Note: Comments starting with /* are not in the configuration file, they are only in the wiki to add some additional information)

<pre>
# Copyright (C) 2013 stepping stone GmbH
# Switzerland
# http://www.stepping-stone.ch
# support@stepping-stone.ch
#
# Authors:
# Pat Kläy <pat.klaey@stepping-stone.ch>
#
# Licensed under the EUPL, Version 1.1.
#
# You may not use this work except in compliance with the
# Licence.
# You may obtain a copy of the Licence at:
#
# http://www.osor.eu/eupl
#
# Unless required by applicable law or agreed to in
# writing, software distributed under the Licence is
# distributed on an "AS IS" basis,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
# express or implied.
# See the Licence for the specific language governing
# permissions and limitations under the Licence.
#

/* If you want, you can override the log information from the global configuration file this might be useful for debugging */
[Global]
# If true the script logs every information to the log-file.
LOG_DEBUG = 1

# If true the script logs additional information to the log-file.
LOG_INFO = 1

#If true the script logs warnings to the log-file.
LOG_WARNING = 1

#If true the script logs errors to the log-file.
LOG_ERR = 1

/* Specify the hosts fully qualified domain name. This name will be used to perform some checks and also appear in the information and error mails */
ENVIRONMENT = <FQDN>

[Database]
BACKEND = LDAP
SERVER = ldaps://ldapm.tombstone.org
PORT = 636
ADMIN_USER = cn=Manager,dc=stoney-cloud,dc=org
ADMIN_PASSWORD = <PASSWORD>
SERVICE_SUBTREE = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
COOKIE_FILE = /etc/Provisioning/Backup/rsnapshot.cookie
DEFAULT_COOKIE = rid=001,csn=
SEARCH_FILTER = (&(entryCSN>=%entryCSN%)(sstProvisioningState=0))

/* Specifies the service itself. As it is the prov-backup-rsnapshot module, the SERVICE is "Backup" and the TYPE is "Rsnapshot".
* The MODUS is as usual selfcare and the TRANSPORTAPI is LocalCLI. This is because the daemon is running on the same host as the
* backup accounts are provisioned and the commands can be executed on this host using the cli.
* For more information about MODUS and TRANSPORTAPI see https://int.stepping-stone.ch/wiki/provisioning.pl#Service_Konfiguration
*/
[Service]
MODUS = selfcare
TRANSPORTAPI = LocalCLI
SERVICE = Backup
TYPE = Rsnapshot

SYSLOG = prov-backup-rsnapshot

/* For the TRANSPORTAPI LocalCLI there is no gateway required because there is no connection to establish. So set HOST, USER and
* DSA_FILE to whatever you want. Don't leave it blank, otherwise the provisioning daemon would log some error messages saying
* these attributes are empty
*/
[Gateway]
HOST = localhost
USER = provisioning
DSA_FILE = none

/* Information about the backup itself (how to setup everything). Note that the %uid% int the RSNAPSHOT_CONFIG_FILE parameter will
* be replaced by the accounts UID. The script CREATE_CHROOT_CMD was installed with the prov-backup-rsnapshot module, so do not
* change this parameter. The quota parameters (SET_QUOTA_CMD, MOUNTPOINT, QUOTA_FILE, PROJECTS_FILE and PROJID_FILE) represent
* the quota setup as described on http://wiki.stoney-cloud.org/index.php/stoney_backup:_Server_set-up#Quota. If you followed this
* manual, you can copy-paste them into your configuration file, otherwise adapt them according to your quota setup.
*/
[Backup]
RSNAPSHOT_CONFIG_FILE = /etc/rsnapshot/rsnapshot.conf.%uid%
SET_QUOTA_CMD = /usr/sbin/xfs_quota
CREATE_CHROOT_CMD = /usr/libexec/createBackupDirectory.sh
MOUNTPOINT = /var
QUOTA_FILE = /etc/backupSize
PROJECTS_FILE = /etc/projects
PROJID_FILE = /etc/projid
</pre>

= Communication with LDAP =
The daemon "communicates" with the LDAP to let other processes know its current state. The important attributes therefore are '''sstProvisioningMode''' and '''sstProvisioningState''' in the given Backup-Account entry. The sequence is defined for adding, modifying or deleting an entry. The preconditions for all three modi are:
* sstProvisioningMode is set to add, modify or delete
* sstProvisioningState is set to 0
* sstProvisioningDate is set to 0 or the current date (format: YYYYMMDD)

== Add ==
=== Precondition ===
<source lang="ldif">
...
sstProvisioningMode: add
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: adding
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: added
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

== Modify ==
=== Precondition ===
<source lang="ldif">
...
sstProvisioningMode: modify
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: modifying
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon has finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: modified
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

== Delete ==
=== Precondition ===
<source lang="ldif">
...
sstIsActive: FALSE
sstProvisioningMode: delete
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>

=== Step 1 ===
<source lang="ldif">
...
sstProvisioningMode: deleting
sstProvisioningState: 0
sstProvisioningDate: 0
...
</source>
Now the prov-backup-rsnapshot daemon works on the given entry.
=== Step 2 ===
As soon as the prov-backup-rsnapshot daemon finished working on the given entry:
<source lang="ldif">
...
sstProvisioningMode: deleted
sstProvisioningState: YYYYMMDDThhmmssZ
sstProvisioningDate: 0
...
</source>

= Source Code =
The source code is located in our GitHub Repository:

https://github.com/stepping-stone/prov-backup-rsnapshot

== Exit Codes ==
The following list defines the return codes and their meaning for the ...:
<pre>
use constant
{
SUCCESS => 0,
UNDEFINED_ERROR => 1,
USER_NOT_PRESENT_IN_BACKEND => 2,
PERL_VERSION_NOT_STATISFIED => 3,
CANNOT_CHECK_HOME_DIR_PRESENCE => 4,
CANNOT_CREATE_HOME_DIR => 5,
CANNOT_SET_QUOTA => 6,
CANNOT_CREATE_RSNAPSHOT_CONFIGURATION => 7,
};
</pre>

= Testing =
== Requirements ==
A working test server set up following the [[stoney_backup:_Server_set-up#prov-backup-rsnapshot | stoney backup: Server set-up]] guide.

== Test the daemon ==
* The daemon is running on the Backup-Server VM (kvm-0036)
** Open a terminal and login to the Backup-Server VM
** <pre>tail -f /var/log/syslog/provisioning.log</pre>
* Open a second terminal and login to the Backup-Server VM
** Make sure the directory /root/data exists, if not create it
** Create an online backup account by executing the test script:
** <pre>/usr/libexec/createBackupDirectory.sh --uid 3724300</pre>
** The test script currently supports the following options:
*** --uid <UID>: Mandatory option, the backup accounts uid
*** --reseller <UID>: Optional, sets sstBelongsToResellerUID (default 4000000)
*** --customer <UID>: Optional, sets sstBelongsToCustomerUID (default 4000001)
*** --people <UID>: Optional, sets sstBelongsToPersonUID (default 4000002)
*** --givenname <Name>: Optional, sets the givenname attribute (default "Givenname")
*** --surname <Name>: Optional, sets the sn attribute (defualt "Surname")
** Load the generated LDIF (you find them under /root/data) step by step into the LDAP and observe what the deamon is doing in the first terminal:
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/01_add_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/02_modify_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/03_delete_3724300.ldif</pre>
*** <pre>/root/loadOpenLDAPsingleLDIF.sh /root/data/04_remove_3724300.ldif</pre>

= Links =

[[Category:stoney backup]][[Category:Provisioning Modules]]

stoney backup: Server set-up

2014-06-19T07:58:12Z

Chrigu: /* Provisioning global configuration */

= Abstract =
This document describes server setup for the stoney cloud (Online) Backup service, built upon the [http://www.gentoo.org/ Gentoo] Linux distribution.

= Overview =
After working through this documentation, you will be able to set up and configure your own (Online) Backup service server.

= Software Installation =

== Requirements ==
A working stoney cloud, installed according to [[stoney cloud: Single-Node Installation]] or [[stoney cloud: Multi-Node Installation]].

== Keywords & USE-Flags ==
For a minimal OpenLDAP directory installation:
echo "net-nds/openldap minimal sasl" >> /etc/portage/package.use
echo "net-nds/openldap ~amd64" >> /etc/portage/package.keywords

NSS and PAM modules for lookups using LDAP:
echo "sys-auth/nss-pam-ldapd sasl" >> /etc/portage/package.use
echo "sys-auth/nss-pam-ldapd ~amd64" >> /etc/portage/package.keywords
echo "sys-fs/quota ldap" >> /etc/portage/package.use

echo "=app-admin/jailkit-2.16 ~amd64" >> /etc/portage/package.keywords

For the prov-backup-rsnapshot daemon:
echo "dev-perl/Net-SMTPS ~amd64" >> /etc/portage/package.keywords
echo "perl-core/Switch ~amd64" >> /etc/portage/package.keywords

To build puttygen only without X11:
echo "net-misc/putty ~amd64" >> /etc/portage/package.keywords
echo "net-misc/putty -gtk" >> /etc/portage/package.use

== Emerge ==
emerge -va nss-pam-ldapd \
quota \
net-misc/putty \
app-admin/jailkit \
sys-apps/haveged \
net-misc/putty \
sys-apps/sst-backup-utils \
sys-apps/sst-prov-backup-rsnapshot

To list the dependencies of ebuilds, you can use <code>equery</code>:
equery depgraph sst-backup-utils
<pre>
* Searching for sst-backup-utils ...

* dependency graph for sys-apps/sst-backup-utils-0.1.0
`-- sys-apps/sst-backup-utils-0.1.0 amd64
`-- dev-perl/PerlUtil-0.1.0 (>=dev-perl/PerlUtil-0.1.0) amd64
`-- virtual/perl-Sys-Syslog-0.320.0 (virtual/perl-Sys-Syslog) amd64
`-- dev-perl/perl-ldap-0.530.0 (dev-perl/perl-ldap) amd64
`-- dev-perl/XML-Simple-2.200.0 (dev-perl/XML-Simple) amd64
`-- dev-perl/Config-IniFiles-2.780.0 (dev-perl/Config-IniFiles) amd64
`-- dev-perl/XML-Validator-Schema-1.100.0 (dev-perl/XML-Validator-Schema) amd64
`-- dev-perl/Date-Calc-6.300.0 (dev-perl/Date-Calc) amd64
`-- dev-perl/DateManip-6.310.0 (dev-perl/DateManip) amd64
`-- dev-perl/Schedule-Cron-Events-1.930.0 (dev-perl/Schedule-Cron-Events) amd64
`-- dev-perl/DateTime-Format-Strptime-1.520.0 (dev-perl/DateTime-Format-Strptime) amd64
`-- dev-perl/XML-SAX-0.990.0 (dev-perl/XML-SAX) amd64
`-- virtual/perl-MIME-Base64-3.130.0-r2 (virtual/perl-MIME-Base64) amd64
`-- dev-perl/Authen-SASL-2.160.0 (dev-perl/Authen-SASL) amd64
`-- dev-perl/Net-SMTPS-0.30.0 (dev-perl/Net-SMTPS) ~amd64
`-- dev-perl/text-template-1.450.0 (dev-perl/text-template) amd64
`-- virtual/perl-Getopt-Long-2.380.0-r2 (virtual/perl-Getopt-Long) amd64
`-- dev-perl/Parallel-ForkManager-1.20.0 (dev-perl/Parallel-ForkManager) amd64
`-- dev-perl/Time-Stopwatch-1.0.0 (dev-perl/Time-Stopwatch) amd64
`-- app-backup/rsnapshot-1.3.1-r1 (app-backup/rsnapshot) amd64
[ sys-apps/sst-backup-utils-0.1.0 stats: packages (20), max depth (1) ]
</pre>

For more information, visit the [http://www.gentoo.org/doc/en/gentoolkit.xml Gentoolkit] page.

= Base Server Software Configuration =
== OpenSSH ==
=== OpenSSH Configuration ===
Configure the OpenSSH daemon:
<source lang="bash">
vi /etc/ssh/sshd_config
</source>

Set following options:
<source lang="bash">
PubkeyAuthentication yes
PasswordAuthentication yes
UsePAM yes
Subsystem sftp internal-sftp
</source>

Make sure, that <code>Subsystem sftp internal-sftp</code> is the last line in the configuration file.

We want to reduce the numbers of chroot environments in one folder. As the <code>ChrootDirectory</code> configuration option only allows <code>%h</code> (home directory of the user) and <code>%u</code> (username of the user), we need to create the necessary matching rules in the form of:
<source lang="bash">
Match User *000
ChrootDirectory /var/backup/000/%u
AuthorizedKeysFile /var/backup/000/%u/%h/.ssh/authorized_keys
Match
Match User *001
ChrootDirectory /var/backup/001/%u
AuthorizedKeysFile /var/backup/001/%u/%h/.ssh/authorized_keys
Match
...
Match User *999
ChrootDirectory /var/backup/999/%u
AuthorizedKeysFile /var/backup/999/%u/%h/.ssh/authorized_keys
Match
</source>

The creation of the matching rules is done by executing the following bash commands:
<source lang="bash">
FILE=/etc/ssh/sshd_config;

for x in {0..999} ; do \
printf "Match User *%03d\n" $x >> ${FILE}; \
printf " ChrootDirectory /var/backup/%03d/%%u\n" $x >> ${FILE}; \
printf " AuthorizedKeysFile /var/backup/%03d/%%u/%%h/.ssh/authorized_keys\n" $x >> ${FILE}; \
printf "Match\n" >> ${FILE}; \
done
</source>

Don't forget to restart the OpenSSH daemon:
<source lang="bash">
/etc/init.d/sshd restart
</source>

=== OpenSSH Host Keys ===
If you migrate from a existing backup server, you might want to copy the ssh host keys to the new server. If you do so clients want see a difference between the two hosts as the fingerprint remains the same. Copy the following files from the existing host to the new:
* /etc/ssh/ssh_host_dsa_key
* /etc/ssh/ssh_host_ecdsa_key
* /etc/ssh/ssh_host_key
* /etc/ssh/ssh_host_rsa_key
* /etc/ssh/ssh_host_dsa_key.pub
* /etc/ssh/ssh_host_ecdsa_key.pub
* /etc/ssh/ssh_host_key.pub
* /etc/ssh/ssh_host_rsa_key.pub

Set the correct permissions on the new host:
chmod 600 /etc/ssh/ssh_host_dsa_key /etc/ssh/ssh_host_ecdsa_key /etc/ssh/ssh_host_key /etc/ssh/ssh_host_rsa_key
chmod 644 /etc/ssh/*.pub

And restart the ssh daemon. ''Caution'': do not close your existing ssh session as long as you are not sure the ssh daemon has restarted properly and you can login again.
/etc/init.d/sshd restart

== OpenLDAP ==
=== /etc/hosts ===
Update the <code>/etc/hosts</code> with the LDAP server:
/etc/hosts

# VIP of the LDAP Server
31.216.40.4 ldapm.stoney-cloud.org

=== Root CA Certificate Installation ===
Install the root CA certificate into the OpenSSL default certificate storage directory:
fqdn="cloud.stoney-cloud.org" # The fully qualified domain name of the server containing the root certificate.

cd /etc/ssl/certs/
wget --no-check-certificate https://${fqdn}/ca/FOSS-Cloud_CA.cert.pem
chown root:root /etc/ssl/certs/FOSS-Cloud_CA.cert.pem
chmod 444 /etc/ssl/certs/FOSS-Cloud_CA.cert.pem

Rebuild the CA hashes
c_rehash /etc/ssl/certs/

=== /etc/openldap/ldap.conf ===
Update the <code>/etc/openldap/ldap.conf</code>LDAP configuration file/environment variables:
/etc/openldap/ldap.conf

<pre>
# Used to specify a size limit to use when performing searches. The number should be an
# non-negative integer. SIZELIMIT of zero (0) specifies unlimited search size.
SIZELIMIT 20000

# Used to specify a time limit to use when performing searches. The number should be an
# non-negative integer. TIMELIMIT of zero (0) specifies unlimited search time to be used.
TIMELIMIT 45

# Specify how aliases dereferencing is done. DEREF should be set to one of never, always, search,
# or find to specify that aliases are never dereferenced, always dereferenced, dereferenced when
# searching, or dereferenced only when locating the base object for the search. The default is to
# never dereference aliases.
DEREF never

# Specifies the URI(s) of an LDAP server(s) to which the LDAP library should connect. The URI
# scheme may be either ldapor ldaps which refer to LDAP over TCP and LDAP over SSL (TLS)
# respectively. Each server's name can be specified as a domain- style name or an IP address
# literal. Optionally, the server's name can followed by a ':' and the port number the LDAP
# server is listening on. If no port number is provided, the default port for the scheme is
# used (389 for ldap://, 636 for ldaps://). A space separated list of URIs may be provided.
URI ldaps://ldapm.stoney-cloud.org

# Used to specify the default base DN to use when performing ldap operations. The base must be
# specified as a Distinguished Name in LDAP format.
BASE dc=stoney-cloud,dc=org

# This is a local copy of the certificate of the certificate authority
# used to sign the server certificate for the LDAP server I am using
TLS_CACERT /etc/ssl/certs/FOSS-Cloud_CA.cert.pem
</pre>

Check you configuration by doing a search:
ldapsearch -v -H "ldaps://ldapm.stoney-cloud.org" \
-b "dc=stoney-cloud,dc=org" \
-D "cn=Manager,dc=stoney-cloud,dc=org" \
-s one "(objectClass=*)" \
-LLL -W

The result should look something like:
ldap_initialize( ldaps://ldapm.stoney-cloud.org:636/??base )
filter: (objectClass=*)
requesting: All userApplication attributes
dn: ou=administration,dc=stoney-cloud,dc=org
objectClass: top
objectClass: organizationalUnit
ou: administration
...

== Random Number Generator (haveged) ==
Tools like putty are dependent on random numbers to be able to create certificates.

=== haveged - Generate random numbers and feed linux random device ===
The haveged daemon doesn't need any special configuration, therefore you can start it from the command line interface:
/etc/init.d/haveged start

Check, if the start was successful:
ps auxf | grep haveged

root 18001 1.0 0.0 7420 3616 ? Ss 08:48 0:00 /usr/sbin/haveged -r 0 -w 1024 -v 1

Add the haveged daemon to the default run level:
rc-update add haveged default

== nss-pam-ldapd ==
=== nslcd.conf — configuration file for LDAP nameservice daemon ===
/etc/nslcd.conf

<pre>
# This is the configuration file for the LDAP nameservice
# switch library's nslcd daemon. It configures the mapping
# between NSS names (see /etc/nsswitch.conf) and LDAP
# information in the directory.
# See the manual page nslcd.conf(5) for more information.

# The user and group nslcd should run as.
uid nslcd
gid nslcd

# The uri pointing to the LDAP server to use for name lookups.
# Multiple entries may be specified. The address that is used
# here should be resolvable without using LDAP (obviously).
#uri ldap://127.0.0.1/
#uri ldaps://127.0.0.1/
#uri ldapi://%2fvar%2frun%2fldapi_sock/
# Note: %2f encodes the '/' used as directory separator
uri ldaps://ldapm.tombstone.ch

# The LDAP version to use (defaults to 3
# if supported by client library)
#ldap_version 3

# The distinguished name of the search base.
base dc=stoney-cloud,dc=org

# The distinguished name to bind to the server with.
# Optional: default is to bind anonymously.
binddn cn=Manager,dc=stoney-cloud,dc=org

# The credentials to bind with.
# Optional: default is no credentials.
# Note that if you set a bindpw you should check the permissions of this file.
bindpw myverysecretpassword

# The distinguished name to perform password modifications by root by.
#rootpwmoddn cn=admin,dc=example,dc=com

# The default search scope.
#scope sub
#scope one
#scope base

# Customize certain database lookups.
#base group ou=Groups,dc=example,dc=com
base group ou=groups,ou=backup,ou=services,dc=stoney-cloud,dc=org
base passwd ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
base shadow ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
#scope group onelevel
#scope hosts sub

#filter group (&(objectClass=posixGroup)(sstIsActive=TRUE))
filter passwd (&(objectClass=posixAccount)(sstIsActive=TRUE))
filter shadow (&(objectClass=shadowAccount)(sstIsActive=TRUE))

# Bind/connect timelimit.
#bind_timelimit 30

# Search timelimit.
#timelimit 30

# Idle timelimit. nslcd will close connections if the
# server has not been contacted for the number of seconds.
#idle_timelimit 3600

# Use StartTLS without verifying the server certificate.
#ssl start_tls
tls_reqcert never

# CA certificates for server certificate verification
#tls_cacertdir /etc/ssl/certs
#tls_cacertfile /etc/ssl/ca.cert

# Seed the PRNG if /dev/urandom is not provided
#tls_randfile /var/run/egd-pool

# SSL cipher suite
# See man ciphers for syntax
#tls_ciphers TLSv1

# Client certificate and key
# Use these, if your server requires client authentication.
#tls_cert
#tls_key

# Mappings for Services for UNIX 3.5
#filter passwd (objectClass=User)
#map passwd uid msSFU30Name
#map passwd userPassword msSFU30Password
#map passwd homeDirectory msSFU30HomeDirectory
#map passwd homeDirectory msSFUHomeDirectory
#filter shadow (objectClass=User)
#map shadow uid msSFU30Name
#map shadow userPassword msSFU30Password
#filter group (objectClass=Group)
#map group member msSFU30PosixMember

# Mappings for Services for UNIX 2.0
#filter passwd (objectClass=User)
#map passwd uid msSFUName
#map passwd userPassword msSFUPassword
#map passwd homeDirectory msSFUHomeDirectory
#map passwd gecos msSFUName
#filter shadow (objectClass=User)
#map shadow uid msSFUName
#map shadow userPassword msSFUPassword
#map shadow shadowLastChange pwdLastSet
#filter group (objectClass=Group)
#map group member posixMember

# Mappings for Active Directory
#pagesize 1000
#referrals off
#idle_timelimit 800
#filter passwd (&(objectClass=user)(!(objectClass=computer))(uidNumber=*)(unixHomeDirectory=*))
#map passwd uid sAMAccountName
#map passwd homeDirectory unixHomeDirectory
#map passwd gecos displayName
#filter shadow (&(objectClass=user)(!(objectClass=computer))(uidNumber=*)(unixHomeDirectory=*))
#map shadow uid sAMAccountName
#map shadow shadowLastChange pwdLastSet
#filter group (objectClass=group)

# Alternative mappings for Active Directory
# (replace the SIDs in the objectSid mappings with the value for your domain)
#pagesize 1000
#referrals off
#idle_timelimit 800
#filter passwd (&(objectClass=user)(objectClass=person)(!(objectClass=computer)))
#map passwd uid cn
#map passwd uidNumber objectSid:S-1-5-21-3623811015-3361044348-30300820
#map passwd gidNumber objectSid:S-1-5-21-3623811015-3361044348-30300820
#map passwd homeDirectory "/home/$cn"
#map passwd gecos displayName
#map passwd loginShell "/bin/bash"
#filter group (|(objectClass=group)(objectClass=person))
#map group gidNumber objectSid:S-1-5-21-3623811015-3361044348-30300820

# Mappings for AIX SecureWay
#filter passwd (objectClass=aixAccount)
#map passwd uid userName
#map passwd userPassword passwordChar
#map passwd uidNumber uid
#map passwd gidNumber gid
#filter group (objectClass=aixAccessGroup)
#map group cn groupName
#map group gidNumber gid
</pre>

=== nsswitch.conf - Name Service Switch configuration file ===
/etc/nsswitch.conf

<pre>
passwd: files ldap
shadow: files ldap
group: files ldap

# passwd: db files nis
# shadow: db files nis
# group: db files nis

hosts: files dns
networks: files dns

services: db files
protocols: db files
rpc: db files
ethers: db files
netmasks: files
netgroup: files
bootparams: files

automount: files
aliases: files
</pre>

=== system-auth ===
vi /etc/pam.d/system-auth

<pre>
auth required pam_env.so
auth sufficient pam_unix.so try_first_pass likeauth nullok
auth sufficient pam_ldap.so minimum_uid=1000 use_first_pass
auth required pam_deny.so

account required pam_unix.so
account sufficient pam_ldap.so minimum_uid=1000 use_first_pass

password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 retry=3
password required pam_unix.so try_first_pass use_authtok nullok sha512 shadow
password sufficient pam_ldap.so minimum_uid=1000 use_first_pass
password required pam_deny.so

session required pam_limits.so
session required pam_env.so
session required pam_unix.so
session sufficient pam_ldap.so minimum_uid=1000 use_first_pass
</pre>

=== Test the Setup ===
nslcd -d

=== Update the Default Run Levels ===
rc-update add nslcd default
rc-update add nscd default

=== Start the necessary Daemons ===
/etc/init.d/nslcd start
/etc/init.d/nscd start

== Quota ==
=== 32-bit Project Identifier Support ===
We need to enable 32-bit project identifier support (PROJID32BIT feature) for our naming scheme (uid numbers larger than 65'536), which is already the default on the stepping stone virtual machines:
mkfs.xfs '''-i projid32bit=1''' /dev/vg-local-01/var

=== Update /etc/fstab and Mount ===
Make sure, that you have user quota (uqota) and project quota (pquota) set as options on the chosen mount point in /etc/fstab. For example:
LABEL=LV-VAR /var xfs noatime,discard,inode64,uquota,pquota 0 2

reboot

Check, if everything went ok:
df -h | grep var

/dev/mapper/vg--local--01-var 1023G 220G 804G 22% /var

=== Verify ===
Some important options for xfs_quota:
* -x: Enable expert mode.
* -c: Pass arguments on the command line. Multiple arguments may be given.

Remount the file system /var and check, if /var has the desired values:
xfs_quota -x -c state /var

As you can see (items marked bold), we have achieved our goal:
User quota state on /var (/dev/mapper/vg--local--01-var)
Accounting: '''ON'''
Enforcement: '''ON'''
Inode: #131 (1 blocks, 1 extents)
Group quota state on /var (/dev/mapper/vg--local--01-var)
Accounting: OFF
Enforcement: OFF
Inode: #132 (1 blocks, 1 extents)
Project quota state on /var (/dev/mapper/vg--local--01-var)
Accounting: '''ON'''
Enforcement: '''ON'''
Inode: #132 (1 blocks, 1 extents)
Blocks grace time: [7 days 00:00:30]
Inodes grace time: [7 days 00:00:30]
Realtime Blocks grace time: [7 days 00:00:30]

=== User Quotas ===
==== Adding a User Quota ====
Set a quota of 1 Gigabyte for the user 4000187 (the values are in kilobytes, so 1048576 kilobyte are 1024 megabytes which corresponds to 1 gigabyte):
xfs_quota -x -c 'limit bhard=1048576k 4000187' /var

Or in bytes:
xfs_quota -x -c 'limit bhard=1073741824 4000187' /var

Read the quota information for the user 4000187:
xfs_quota -x -c 'quota -v -N -u 4000187' /var

/dev/mapper/vg--local--01-var 0 0 1048576 00 [--------] /var

If the user has data in the project, that belongs to him, the result will change:
/dev/mapper/vg--local--01-var 512000 0 1048576 00 [--------] /var

==== Modifiying a User Quota ====
To modify a users quota, you just set a new quota (limit):
xfs_quota -x -c 'limit bhard=1048576k 4000187' /var

Read the quota information for the user 4000187:
xfs_quota -x -c 'quota -v -N -u 4000187' /var

/dev/mapper/vg--local--01-var 0 0 1048576 00 [--------] /var

If the user has data in the project, that belongs to him, the result will change:
/dev/mapper/vg--local--01-var 512000 0 1048576 00 [--------] /var

==== Removing a User Quota ====
Removing a quota for a user:
xfs_quota -x -c 'limit bhard=0 4000187' /var

The following command should give you an empty result:
xfs_quota -x -c 'quota -v -N -u 4000187' /var

=== Project (Directory) Quotas ===
==== Adding a Project (Directory) Quota ====
The XFS file system additionally allows you to set quotas on individual directory hierarchies in the file system that are known as managed trees. Each managed tree is uniquely identified by a project ID and an optional project name. We'll use the following values in the examples:
* project_ID: The uid of the online backup account (4000187).
* project_name: The uid of the online backup account (4000187). This could be a human readable name.
* mountpoint: The mountpoint of the xfs-filesystem (/var). See the <code>/etc/fstab</code> entry from above.
* directory: The directory of the project (187/4000187), starting from the mountpoint of the xfs-filesystem (/var).

Define a unique project ID for the directory hierarchy in the <code>/etc/projects</code> file (project_ID:mountpoint/directory):
echo "4000187:/var/backup/187/4000187/home/4000187" >> /etc/projects

Create an entry in the <code>/etc/projid</code> file that maps a project name to the project ID (project_name:project_ID):
echo "4000187:4000187" >> /etc/projid

Set Project:
xfs_quota -x -c 'project -s -p /var/backup/187/4000187/home/4000187 4000187' /var

Set Quota (limit) on Project:
xfs_quota -x -c 'limit -p bhard=1048576k 4000187' /var

Check your Quota (limit)
xfs_quota -x -c 'quota -p 4000187' /var

Check the Quota:
* <code>-v</code>: increase verbosity in reporting (also dumps zero values).
* <code>-N</code>: suppress the initial header.
* <code>-p</code>: display project quota information.
* <code>-h</code>: human readable format.
xfs_quota -x -c 'quota -v -N -p 4000187' /var

/dev/mapper/vg--local--01-var 0 0 1048576 00 [--------] /var

If you copied data into the project, the output will look something like:
/dev/mapper/vg--local--01-var 512000 0 1048576 00 [--------] /var

To give you an overall view of the whole system:
xfs_quota -x -c report /var

<pre>
User quota on /var (/dev/mapper/vg--local--01-var)
Blocks
User ID Used Soft Hard Warn/Grace
---------- --------------------------------------------------
root 1024000 0 0 00 [--------]
4000187 0 0 1048576 00 [--------]

Project quota on /var (/dev/mapper/vg--local--01-var)
Blocks
Project ID Used Soft Hard Warn/Grace
---------- --------------------------------------------------
4000187 512000 0 1048576 00 [--------]
</pre>

==== Modifying a Project (Directory) Quota ====
To modify a project (directory) quota, you just set an new quota (limit) on the chosen project:
xfs_quota -x -c 'limit -p bhard=1048576k 4000187' /var

Check your quota (limit)
xfs_quota -x -c 'quota -p 4000187' /var

==== Removing a Project (Directory) Quota ====
Removing a quota from a project:
xfs_quota -x -c 'limit -p bhard=0 4000187' /var

Chreck the results:
xfs_quota -x -c report /var

<pre>
User quota on /var (/dev/mapper/vg--local--01-var)
Blocks
User ID Used Soft Hard Warn/Grace
---------- --------------------------------------------------
root 512000 0 0 00 [--------]
4000187 0 0 1024 00 [--------]
</pre>

As you can see, the line with the Project ID 4000187 has disappeared:
4000187 512000 0 1048576 00 [--------]

Don't forget to remove the project from <code>/etc/projects</code> and <code>/etc/projid</code>:
sed -i -e '/4000187/d' /etc/projects
sed -i -e '/4000187/d' /etc/projid

=== Some important notes concerning XFS ===
# The '''quotacheck''' command has no effect on XFS filesystems. The first time quota accounting is turned on (at mount time), XFS does an automatic quotacheck internally; afterwards, the quota system will always be completely consistent until quotas are manually turned off.
# There is '''no need for quota file(s)''' in the root of the XFS filesystem.

== prov-backup-rsnapshot ==
Install the [[stoney_backup:_prov-backup-rsnapshot | prov-backup-rsnasphot ]] daemon script using the package manager:
<pre>
emerge -va sys-apps/sst-prov-backup-rsnapshot
</pre>

=== Configuration ===
If it is the first provisioning module running on this server (very likely) you first have to configure the provisioning daemon (you can skip this step if you have already another provisioning module running on this server)

==== Provisioning global configuration ====
The global configuration for the provisioning daemon applies to all provisioning modules (@PAT: how where they installed? --[[User:Chrigu|Chrigu]] ([[User talk:Chrigu|talk]]) 09:58, 19 June 2014 (CEST)) running on the server. This configuration therefore contains information about the provisioning daemon itself and no information at all about the specific modules.
/etc/Provisioning/Global.conf
<pre>
# Copyright (C) 2012 stepping stone GmbH
# Switzerland
# http://www.stepping-stone.ch
# support@stepping-stone.ch
#
# Authors:
# Pat Kläy <pat.klaey@stepping-stone.ch>
#
# Licensed under the EUPL, Version 1.1.
#
# You may not use this work except in compliance with the
# Licence.
# You may obtain a copy of the Licence at:
#
# http://www.osor.eu/eupl
#
# Unless required by applicable law or agreed to in
# writing, software distributed under the Licence is
# distributed on an "AS IS" basis,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
# express or implied.
# See the Licence for the specific language governing
# permissions and limitations under the Licence.
#

[Global]
# If true the script logs every information to the log-file.
LOG_DEBUG = 0

# If true the script logs additional information to the log-file.
LOG_INFO = 1

#If true the script logs warnings to the log-file.
LOG_WARNING = 1

#If true the script logs errors to the log-file.
LOG_ERR = 1

# The number of seconds to wait before retry contacting the backend server during startup.
SLEEP = 10

# Number of backend server connection retries during startup.
ATTEMPTS = 3

[Operation Mode]
# The number of seconds to wait before retry contacting the backend server in case of a service interruptions.
SLEEP = 30

# Number of backend server connection retries in case of a service interruptions.
ATTEMPTS = 3

[Mail]
# Error messages are sent to the mail configured below.
SENDTO = <YOUR-MAIL-ADDRESS>
HOST = mail.stepping-stone.ch
PORT = 587
USERNAME = <YOUR-NOTIFICATION-EMAIL-ADDRESS>
PASSWORD = <PASSWORD>
FROMNAME = Provisioning daemon
CA_DIR = /etc/ssl/certs
SSL = starttls
AUTH_METHOD = LOGIN

# Additionally, you can be informed about creation, modification and deletion of services.
WANTINFOMAIL = 1
</pre>

==== Provisioning daemon prov-backup-rsnapshot module ====
The module specific configuration is located in /etc/Provisioning/<Service>/<Type>.conf. In the case of the prov-backup-rsnapshot module this is <code>/etc/Provisioning/Backup/Rsnapshot.conf</code>. (Note: Comments starting with /* are not in the configuration file, they are only in the wiki to add some additional information)

<pre>
# Copyright (C) 2013 stepping stone GmbH
# Switzerland
# http://www.stepping-stone.ch
# support@stepping-stone.ch
#
# Authors:
# Pat Kläy <pat.klaey@stepping-stone.ch>
#
# Licensed under the EUPL, Version 1.1.
#
# You may not use this work except in compliance with the
# Licence.
# You may obtain a copy of the Licence at:
#
# http://www.osor.eu/eupl
#
# Unless required by applicable law or agreed to in
# writing, software distributed under the Licence is
# distributed on an "AS IS" basis,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
# express or implied.
# See the Licence for the specific language governing
# permissions and limitations under the Licence.
#

/* If you want, you can override the log information from the global configuration file this might be useful for debugging */
[Global]
# If true the script logs every information to the log-file.
LOG_DEBUG = 1

# If true the script logs additional information to the log-file.
LOG_INFO = 1

#If true the script logs warnings to the log-file.
LOG_WARNING = 1

#If true the script logs errors to the log-file.
LOG_ERR = 1

/* Specify the hosts fully qualified domain name. This name will be used to perform some checks and also appear in the information and error mails */
ENVIRONMENT = <FQDN>

[Database]
BACKEND = LDAP
SERVER = ldaps://ldapm.tombstone.org
PORT = 636
ADMIN_USER = cn=Manager,dc=stoney-cloud,dc=org
ADMIN_PASSWORD = <PASSWORD>
SERVICE_SUBTREE = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
COOKIE_FILE = /etc/Provisioning/Backup/rsnapshot.cookie
DEFAULT_COOKIE = rid=001,csn=
SEARCH_FILTER = (&(entryCSN>=%entryCSN%)(sstProvisioningState=0))

/* Specifies the service itself. As it is the prov-backup-rsnapshot module, the SERVICE is "Backup" and the TYPE is "Rsnapshot".
* The MODUS is as usual selfcare and the TRANSPORTAPI is LocalCLI. This is because the daemon is running on the same host as the
* backup accounts are provisioned and the commands can be executed on this host using the cli.
* For more information about MODUS and TRANSPORTAPI see https://int.stepping-stone.ch/wiki/provisioning.pl#Service_Konfiguration
*/
[Service]
MODUS = selfcare
TRANSPORTAPI = LocalCLI
SERVICE = Backup
TYPE = Rsnapshot

SYSLOG = prov-backup-rsnapshot

/* For the TRANSPORTAPI LocalCLI there is no gateway required because there is no connection to establish. So set HOST, USER and
* DSA_FILE to whatever you want. Don't leave it blank, otherwise the provisioning daemon would log some error messages saying
* these attributes are empty
*/
[Gateway]
HOST = localhost
USER = provisioning
DSA_FILE = none

/* Information about the backup itself (how to setup everything). Note that the %uid% int the RSNAPSHOT_CONFIG_FILE parameter will
* be replaced by the accounts UID. The script CREATE_CHROOT_CMD was installed with the prov-backup-rsnapshot module, so do not
* change this parameter. The quota parameters (SET_QUOTA_CMD, MOUNTPOINT, QUOTA_FILE, PROJECTS_FILE and PROJID_FILE) represent
* the quota setup as described on http://wiki.stoney-cloud.org/index.php/stoney_backup:_Server_set-up#Quota. If you followed this
* manual, you can copy-paste them into your configuration file, otherwise adapt them according to your quota setup.
*/
[Backup]
RSNAPSHOT_CONFIG_FILE = /etc/rsnapshot/rsnapshot.conf.%uid%
SET_QUOTA_CMD = /usr/sbin/xfs_quota
CREATE_CHROOT_CMD = /usr/libexec/createBackupDirectory.sh
MOUNTPOINT = /var
QUOTA_FILE = /etc/backupSize
PROJECTS_FILE = /etc/projects
PROJID_FILE = /etc/projid
</pre>

== backup utils ==
Install the backup utils (multiple scripts which help you to manage and monitor your backup server and backup accounts) using the package manager. For more information about the scripts please see the [[stoney_backup:_Server_set-up#stoney_backup_Service_Software | stoney backup Service Software]] section.
<pre>
emerge -va sys-apps/sst-backup-utils
</pre>
=== Configuration ===
Please refer to the configuration sections for the different scripts in [[stoney_backup:_Server_set-up#stoney_backup_Service_Software | stoney backup Service Software]].

= stoney backup Service Software =
The stoney backup Service comes along with multiple scripts which help you to manage and monitor your backup server and accounts:

We use rsnapshot - remote filesystem snapshot utility for the actual snapshots and a handful of wrapper scripts, that do things like:
* Read the users and their settings from the LDAP directory.
* Execute rsnapshot according to the users settings.
* Write the backup quotas backup (incoming), iterations (.snapshots) and free space to the users local backupSize file and update the LDAP directory.
* Inform the reseller, customer or user (depending on the settings in the LDAP directory) via mail, if the quota limit has been reached.
* Depending on the users settings in the LDAP directory, warning mail will be sent to the reseller, customer or user, if a backup was not executed on time.

== writeAccountSize.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeAccountSize.pl</code> by the <code>sys-apps/sst-backup-utils</code> package and does the following:
* Calculates the used disk space (backup and iterations) for a given account and writes the corresponding values to:
*# The LDAP backend (used by the selfcare webinterface to display quota information):
*#* Backup space used (sstBackupSize): The disk space the account uses for the backup itself (disk space used under the <code>incoming</code> folder of the users chroot-home directory)
*#* Snapshot space used (sstIncrementSize): The disk space the account uses for the iterations (disk space under the <code>.snapshot</code> folder of the users chroot-home directory)
*# The file <code>etc/backupSize</code> of the accounts chroot (used by the Sepiola Online Backup client):
* Checks if the user and/or reseller must be notified that there is no more disk space left for the given account
** Checks if the notification flag was passed, if not no notification will be triggered
** Calculates the used disk space (backup and iterations) in percentage
** Reads the notification threshold value from the LDAP backed
** If the disk space used (in percentage) is bigger than the value retrieved from the LDAP backend start the [[stoney_cloud:_Notification_Architecture | notification]] process with
*** Product: Given account UID
*** Service: Backup
*** Problem: Quota
* Pod documentation:
<pre>
NAME
writeAccountSize.pl

DESCRIPTION
This Script gets quota information from filesystem, size of incoming and
snapshots directories, write the data to a file and the LDAP backend and
sends an e-mail message for each account that is over quota to users
e-mail address (from ldap directory) if notification flag is passed.

The configuration file for this script is stored in the backup-utils
configuration directory (/etc/backup-utils/) and is called
writeAccountSize.conf.

The script needs access to the quota program to get quota information.
The script needs ldap access to get users e-mail address and quota
information. The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

-C configfile
The configuration file.

-U uid
The user id.

-n notification
Start notification process if quota threshold is reached

-d debug
Turns the debug mode on.

-h help
This online help.

USAGE
writeAccountSize.pl -U uid [-C configuration file ] []-d debug] [-h
help] [-n]

CREATED
2009-04-16 michael.rhyner@stepping-stone.ch created

VERSION
2009-04-16 michael.rhyner@stepping-stone.ch created
2009-04-30 michael.rhyner@stepping-stone.ch changed position based quota
output parsing with correctly parsed elements
2009-06-15 michael.rhyner@stepping-stone.ch added over quota check and
sending e-mail
2009-06-16 michael.rhyner@stepping-stone.ch renamed script and make it
more general usable (e.g. for online backup, online storage, ...)
2009-06-17 michael.rhyner@stepping-stone.ch changed mail message to read
from a text file instead from configuration parameter
2009-06-18 michael.rhyner@stepping-stone.ch corrected wrong regex to
weed out the asterisk (*) in getQuotaSize
2009-06-19 michael.rhyner@stepping-stone.ch corrected wrong evaluation
success from subroutines and avoid message output when not in debug mode
2009-06-22 michael.rhyner@stepping-stone.ch getQuotaSize: return
immediately if no quota was set
2009-06-24 michael.rhyner@stepping-stone.ch alert when used certain
percentge of allowed space instead of more than allowed space
2009-06-26 michael.rhyner@stepping-stone.ch values are presented in
Gigabytes within notification message
2009-07-23 michael.rhyner@stepping-stone.ch corrected wrong syslog
severities for errors
2009-07-24 michael.rhyner@stepping-stone.ch made e-mail address
available within message body
2013-08-19 pat.klaey@stepping-stone.ch write quota values also to the
LDAP

INCORPORATED CODE
Incorporate code with use:

warnings;
strict;
Config::IniFiles;
Getopt::Std;
Sys::Syslog;
File::Basename;
Text::Template;
POSIX;
Notification;
PerlUtil::Logging;
PerlUtil::LDAPUtil;
</pre>

=== Configuration ===
/etc/backup-utils/writeAccountSize.conf
<pre>
[Global]
INCOMING_DIRECTORY = /incoming
ACCOUNT_SIZE_FILE = /etc/backupSize
SNAPSHOTS = 1

[Syslog]
SYSLOG = rsnapshot

[Directory]
LDAP_SERVER = ldaps://ldapm.tombstone.ch
LDAP_PORT = 636
LDAP_BIND_DN = cn=Manager,dc=stoney-cloud,dc=org
LDAP_BIND_PW = <password>
LDAP_BASE_DN = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
LDAP_PERSON_BASE = ou=people,dc=stoney-cloud,dc=org
LDAP_RESELLER_BASE = ou=reseller,ou=configuration,ou=backup,ou=services,dc=stoney-cloud,dc=org
LDAP_EMAIL_ATTRIBUTE = mail

[Notification]
EMAIL_SENDER = stepping stone GmbH Supprt <support@stepping-stone.ch>
EMAIL_ALERT_THRESHOLD = 85

Salutation_Default_de-CH = Liebe Kundin / Lieber Kunde
Salutation_m_de-CH = Sehr geehrter Herr
Salutation_f_de-CH = Sehr geehrte Frau
Salutation_Default_en-GB = Dear customer
Salutation_m_en-GB = Dear Mr.
Salutation_f_en-GB = Dear Mrs.
</pre>

=== Tests ===
/usr/libexec/backup-utils/writeAccountSize.pl -U 4000080 -d
<pre>
Debug modus was turned on

Debug sub checkUsersHomeDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersHomeDirectory: The $localUsersHomeDirectory /var/backup/080/4000080/home/4000080 exists

Debug sub checkUsersIncomingDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersIncomingDirectory: $localUsersIncomingDirectory: /incoming
Debug sub checkUsersIncomingDirectory: $localIncomingPath: /var/backup/080/4000080/home/4000080/incoming

Debug sub checkUsersIncomingDirectory: The $localIncomingPath /var/backup/080/4000080/home/4000080/incoming exists
Total Quota: 1048576 kilobytes
Total used Space: 0 kilobytes
Incoming Size: 0 kilobytes
Debug sub getSnapshotsSize: $localUsedQuota: 0
Debug sub getSnapshotsSize: $localSnapshotsSize: 0
Debug writeAccountSize: Working on /var/backup/080/4000080/etc/backupSize
Debug: wrote 1024 0 0 to /var/backup/080/4000080/etc/backupSize
DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstBackupSize => 0

DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstIncrementSize => 0

Alert Threshold: 85 %
Calculated value: 0
</pre>

Now write some data (200 megaytes in this example) into the users incoming directory and then execute the script again:
dd if=/dev/zero of=/var/backup/080/4000080/home/4000080/incoming/test.zeros bs=1024k count=200
chown 4000080:4000080 /var/backup/080/4000080/home/4000080/incoming/test.zeros
/usr/libexec/backup-utils/writeAccountSize.pl -U 4000080 -d

<pre>
Debug modus was turned on

Debug sub checkUsersHomeDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersHomeDirectory: The $localUsersHomeDirectory /var/backup/080/4000080/home/4000080 exists

Debug sub checkUsersIncomingDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersIncomingDirectory: $localUsersIncomingDirectory: /incoming
Debug sub checkUsersIncomingDirectory: $localIncomingPath: /var/backup/080/4000080/home/4000080/incoming

Debug sub checkUsersIncomingDirectory: The $localIncomingPath /var/backup/080/4000080/home/4000080/incoming exists
Total Quota: 1048576 kilobytes
Total used Space: 204800 kilobytes
Incoming Size: 204800 kilobytes
Debug sub getSnapshotsSize: $localUsedQuota: 204800
Debug sub getSnapshotsSize: $localSnapshotsSize: 0
Debug writeAccountSize: Working on /var/backup/080/4000080/etc/backupSize
Debug: wrote 1024 200 0 to /var/backup/080/4000080/etc/backupSize
DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstBackupSize => 209715200

DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstIncrementSize => 0

Alert Threshold: 85 %
Calculated value: 19.53125
</pre>
Everything seems to be working fine!

== snapshot.pl ==
This script is installed to <code>/usr/libexec/backup-utils/snapshot.pl</code> by the <code>sys-apps/sst-backup-utils</code> package and does the following:
* Read interval parameter value passed
** The interval parameter value can be daily, weekly, monthly (or yearly)
* Find all backup active accounts for which the rsnapshot command must be executed (depending on the given interval)
** Filter to find these accounts: <code>(&(sstBackupInterval<INTERVAL>=*)(sstIsActive=TRUE))</code> for example for the daily rsnapshot the filter is <code>(&(sstBackupIntervalDaily=*)(sstIsActive=TRUE))</code>
*** In other words this means: Get me all acounts that have for <code>sstBackupInterval<INTERVAL></code> a value defined AND <code>sstIsActive</code> is set to "TRUE"
* According to the interval given and the account UID calculate the rsnapshot command for all these accounts
** For example
*** Account UID: 4000000
*** Interval: daily
*** Resulting rsnapshot command: /usr/bin/nice -n 19 /usr/bin/rsnapshot -c /etc/rsnapshot/rsnapshot.conf.4000000 daily (if you use the [[#snapshot.pl_Configuration | configuration]] below)
* Execute all these commands
** Use controlled parallel execution, you can specify how many commands can be executed in parallel (see [[#snapshot.pl_Configuration | configuration]] below)
* Pod documentation:
<pre>
NAME
snapshot.pl

DESCRIPTION
This script gets all active online backup accounts from the LDAP backend
for which the rsnapshot process for the given interval must be executed.
According to these accounts and the given interval, the commands to be
executed are generated and finally executed. The commands can be
executed in parallel, however there is a limit defined in the
configuration file which limits the amount of parallel running
processes.

USAGE
./snapshot.pl --interval interval [--debug] [--help]

OPTIONS
--interval/-i interval
Specifies the rsnapshot interval (can be hourly, daily, weekly,
monthly or yearly)

--debug/-d
Turns on debug mode

--help/-h
Shows this help

CREATED
2012-03-19 pat.klaey@stepping-stone.ch created

VERSION
2012-03-19 pat.klaey@stepping-stone.ch created

INCORPORATED CODE
Incorporated code with use:

warnings;
strict;
Getopt::Long;
Sys::Syslog;
PerlUtil::Logging;
PerlUtil::LDAPUtil;
File::Basename;
Parallel::ForkManager;
Time::Stopwatch;
</pre>

=== Configuration ===
There are two things to do in this step:
* Configure the rsnapshot root directory
* Configure the snapshot.pl script itself

==== rsnaphot configuration directory ====
The users individual rsnapshot configurations are stored under <code>/etc/rsnapshot</code>. Please make sure, that the directory exists:
ls -al /etc | grep rsnapshot

drwx------ 2 root root 64 30. Aug 20:20 rsnapshot

If not, create it:
mkdir /etc/rsnapshot
chmod 700 /etc/rsnapshot

==== snapshot.pl Configuration ====
The snapshot.pl script is responsible for the execution of rsnapshot according to the users settings.
/etc/backup-utils/snapshot.conf
<pre>
[General]
MaxParallelProcesses = 5
Rsnapshot_command = /usr/bin/nice -n 19 /usr/bin/rsnapshot -c /etc/rsnapshot/rsnapshot.conf.%uid% %interval%

[LDAP]
Host = ldaps://ldapm.tombstone.ch
Port = 636
User = cn=Manager,dc=stoney-cloud,dc=org
Password = <Password>
CA_Path = /etc/ssl/certs
Accounts_Base = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
</pre>

Legend: At runtime the following placeholders are replaced as follows
* '''%uid%''': The backup account and login uid as a numeric number. For example: 4000205.
* '''%interval%''': The backup level to be executed. Possible values are hourly, daily, weekly, monthly and yearly.

=== Tests ===
Before adding the necessary cronjob entries, we need to make sure, that we've configured the snapshot.pl script correctly:
/usr/libexec/backup-utils/snapshot.pl --interval daily -d

If everything worked as planned, you should receive feedback looking roughly like:
<pre>
INFO: Starting rsnapshot for interval daily with maximum 5 parallel processes

INFO: Executing snapshot for 4000080

INFO: Executing snapshot for 4000079

INFO: Snapshot process for 4000079 finished in 0.18 seconds with status 0

INFO: Snapshot process for 4000080 finished in 0.19 seconds with status 0

INFO: rsnapshot for all backups done. Took 0.24 seconds
</pre>

Just to make sure, that everything did work out fine, execute <code>writeAccountSize.pl</code> again:
/usr/libexec/backup-utils/writeAccountSize.pl -U 4000080 -d
<pre>
Debug modus was turned on

Debug sub checkUsersHomeDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersHomeDirectory: The $localUsersHomeDirectory /var/backup/080/4000080/home/4000080 exists

Debug sub checkUsersIncomingDirectory: $localUsersHomeDirectory: /var/backup/080/4000080/home/4000080
Debug sub checkUsersIncomingDirectory: $localUsersIncomingDirectory: /incoming
Debug sub checkUsersIncomingDirectory: $localIncomingPath: /var/backup/080/4000080/home/4000080/incoming

Debug sub checkUsersIncomingDirectory: The $localIncomingPath /var/backup/080/4000080/home/4000080/incoming exists
Total Quota: 1048576 kilobytes
Total used Space: 409600 kilobytes
Incoming Size: 204800 kilobytes
Debug sub getSnapshotsSize: $localUsedQuota: 409600
Debug sub getSnapshotsSize: $localSnapshotsSize: 204800
Debug writeAccountSize: Working on /var/backup/080/4000080/etc/backupSize
Debug: wrote 1024 200 200 to /var/backup/080/4000080/etc/backupSize
DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstBackupSize => 209715200

DEBUG: Successfully executed the following modifications for entry uid=4000080,ou=accounts,ou=backup,ou=services,o=stepping-stone,c=ch: sstIncrementSize => 209715200

Alert Threshold: 85 %
Calculated value: 39.0625
</pre>

As you can see, the total used space has risen to 39.0625.

=== Cronjobs ===
After making sure, that everything worked as planned, you can update your crontab entry:
crontab -e
<pre>
...
# Rsnapshot for all users
30 22 * * * /usr/libexec/backup-utils/snapshot.pl --interval daily
15 22 * * sun /usr/libexec/backup-utils/snapshot.pl --interval weekly
00 22 1 * * /usr/libexec/backup-utils/snapshot.pl --interval monthly
...
</pre>

* TBD: Maybe this is not optimal if there is a lot of data to rotate. In this case, it might be that for example weekly and daily snapshot both run at the same time what might lead to strange results.
* Workarounds:
** Simple/short version: Instead one could create another wrapper script which is called everyday and does some simple logic:
** Is today the first day of a month?
*** Yes: Is today sunday?
**** Yes: Execute monthly then weekly then daily rsnapshots using the snapshot.pl script (but wait for each interval to finish before starting the next)
**** No: Execute monthly then daily rsnapshots using the snapshot.pl script (but wait for monthly interval to finish before starting the daily)
*** No: Is today sunday?
**** Yes: Execute weekly then daily rsnapshots using the snapshot.pl script (but wait for weekly interval to finish before starting the daily)
**** No: Execute daily rsnapshots using the snapshot.pl script
** Complex/long version: Adapt the snapshot.pl script and call it every day without interval parameter. The script does the logic described above.
This avoids the above mentioned collision

(Complex) / short version: rule via cronjobs:
<pre>
# Rsnapshot for all users
30 22 * * 1-6 [ $( date +\%d ) -gt 1 ] && /usr/libexec/backup-utils/snapshot.pl --interval daily
15 22 * * 7 [ $( date +\%d ) -gt 1 ] && /usr/libexec/backup-utils/snapshot.pl --interval weekly && /usr/libexec/backup-utils/snapshot.pl --interval daily
00 22 1 * * /usr/libexec/backup-utils/snapshot.pl --interval monthly && /usr/libexec/backup-utils/snapshot.pl --interval weekly && /usr/libexec/backup-utils/snapshot.pl --interval daily
...
</pre>

== scheduleWarning.pl ==
This script is installed to <code>/usr/libexec/backup-utils/scheduleWarning.pl</code> by the <code>sys-apps/sst-backup-utils</code> package and does the following:
* The basic task of this script is simple: For the given account
** Check if the planned backups were started
*** If not, start the [[stoney_cloud:_Notification_Architecture | notification]] process with
**** Product: Given account UID
**** Service: Backup
**** Problem: Schedule
** Check if the planned backups finished successfully
*** If not, start the [[stoney_cloud:_Notification_Architecture | notification]] process with
**** Product: Given account UID
**** Service: Backup
**** Problem: Unsuccessful

As the backup clients distributed by stepping stone GmbH upload metadata XML before (scheduling information and start time) and after (end time and backup status) the actual backup, the scheduleWarning.pl script is able to verify whether or not a planned backup has been executed and whether or not the backup was successful.

* Pod documentation
<pre>
NAME
scheduleWarning.pl

DESCRIPTION
This script tests whether a planed backup was successful or not. There
are two different typs of failure.

1. The Backup did not start
The first type of error is that a backup is scheduled for YYYY-MM-DD
at HH:MM, but the backup don't start at this specified time. A
possible reason could be that the computer was shut down.

2.The backup was not successful
The second type of error is that a backup started as scheduled but
did not finish successfully. There are different reasons for this
error.

If a backup wasn't successful the script checks which type of error
occured. It reads the XML files which are stored on the server and
compares the given information. If the error is detected, the script
stats the norification process with the information of the error.

If a user has more than one computer backed-up, the script tests one
computer after the other. The mail(s) sent by the programm also
contain(s) the information which computer is affected.

OPTION
-U uid
The -U option is required to run the script, it indicates for which
uid the script is executed.

USAGE
scheduleWarning.pl [-U user]

CREATED
2010-04-14 created Pat Kläy <pat.klaey@stepping-stone.ch>

VERSION
2010-04-14 v0.01, created pkl
2010-08-24 v0.02, modified pkl
New using Net::SMTP::TLS to send mails

2013-09-13 v0.03, modified pat.klaey@stepping-stone.ch
Changes to use the script with the new backup infrastructure (read
more information from LDAP, use Notification lib to send mails)

USES
strict;
warnings;
XML::Simple;
Config::IniFiles;
XML::Validator::Schema;
Date::Calc qw(:all);
Date::Manip;
Schedule::Cron::Events;
DateTime::Format::Strptime;
Sys::Syslog;
XML::SAX::ParserFactory;
Getopt::Std;
MIME::Base64;
Authen::SASL;
Net::LDAPS;
Net::SMTP::TLS;
Cwd 'abs_path';
PerlUtil::Logging;
PerlUtil::LDAPUtil;
</pre>

=== Configuration ===
/etc/backup-utils/scheduleWarning.conf
<pre>
[Backup]
CHROOT_DIRECTORY = /var/backup/%lastthree%/%user%

[XML]
SCHEDULE_FILE = %homeDirectory%/incoming/%computerName%/.sepiola_backup/scheduler.xml
SCHEDULE_XSD = /etc/backup-utils/schema/scheduler_schema.xsd
BACKUP_ENDED_FILE = %homeDirectory%/incoming/%computerName%/.sepiola_backup/backupEnded.xml
BACKUP_ENDED_XSD = /etc/backup-utils/schema/backupended_schema.xsd
BACKUP_STARTED_FILE = %homeDirectory%/incoming/%computerName%/.sepiola_backup/backupStarted.xml
BACKUP_STARTED_XSD = /etc/backup-utils/schema/backupstarted_schema.xsd

[TEMPLATE]
Salutation_Default_de-CH = Liebe Kundin / Lieber Kunde
Salutation_m_de-CH = Sehr geehrter Herr
Salutation_f_de-CH = Sehr geehrte Frau
Salutation_Default_en-GB = Dear customer
Salutation_m_en-GB = Dear Mr.
Salutation_f_en-GB = Dear Mrs.

[LDAP]

SERVER = ldaps://ldapm.tombstone.ch
PORT = 636
DEBUG = 1

ADMIN_DN = cn=Manager,dc=stoney-cloud,dc=org
ADMIN_PASSWORD = <Password>

BACKUP_BASE = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
PEOPLE_BASE = ou=people,dc=stoney-cloud,dc=org
RESELLER_BASE = ou=reseller,ou=configuration,ou=backup,ou=services,dc=stoney-cloud,dc=org
SCOPE = sub

</pre>

== checkBackups.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeDate.pl</code> by the <code>sys-apps/sst-backup-utils</code> package. It is a wrapper around the above mentioned <code>writeAccountSize.pl</code> and <code>scheduleWarning.pl</code> scripts (if you configure it accordingly).
* As mentioned the script is a wrapper for calling the quota and scheduler information scripts:
** It gets all active backup accounts from the LDAP directory
** According to the CLI parameters passed it calles for all these accounts:
*** The quota checking script (this script can be defined in the configuration file, see [[stoney_backup:_Server_set-up#Configuration_6 | configuration]] section below)
*** The scheduler checking script (this script can be defined in the configuration file, see [[stoney_backup:_Server_set-up#Configuration_6 | configuration]] section below)
* Pod documentation:
<pre>
NAME
checkBackups.pl

DESCRIPTION
This script processes all active backup accounts and checks (according
to the command line options) the quota and/or the scheduled backups for
the given accounts.

The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

OPTIONS
--schedule/-s
Checks schedule information by calling the defined script

--quota/-s
Checks the quota values by calling the defined script

--notify/-n
Passes the notify flag to the called scripts

USAGE
./checkBackups.pl [--quota] [--schedule] [--notify]

./checkBackups.pl --quota
Checks and writes the quota for all active backup accounts. The user
and/or reseller will NOT be informed if any quota threshold is
reached

./checkBackups.pl --quota --notify
Checks and writes the quota for all active backup accounts. The user
and/or reseller will be informed if any quota threshold is reached.

./checkBackups.pl --schedule
Checkes all active backup account if the scheduled backup was
executed and successful. The --schedule option will allways trigger
a notification mail to the user and/or reseller.

./checkBackups.pl --schedule --quota
Checks both, quota and schedule, for all active backup accounts.
Only schedule will trigger notification mails.

./checkBackups.pl --schedule --quota --notify
Checks both, quota and schedule, for all active backup accounts.
Both, quota and schedule, will trigger notification mails.

CREATED
2013-09-17 pat.klaey@stepping-stone.ch created

VERSION
2013-09-17 pat.klaey@stepping-stone.ch created
2013-11-19 pat.klaey@stepping-stone.ch Added options to be able to check
quota, schedule or both in one run

INCORPORATED CODE
Incorporated code with use:

warnings;
strict;
Getopt::Long;
Sys::Syslog;
Cwd 'abs_path';
File::Basename;
PerlUtil::LDAPUtil;
PerlUtil::Logging;
</pre>

=== Configuration ===
In the configuration you have to define two simple things:
# Which script to call for quota checks and scheduler checks
# How to access the LDAP backend
/etc/backup-utils/checkBackups.conf
<pre>
[Scripts]
CheckQuotaScript = /usr/libexec/backup-utils/writeAccountSize.pl
CheckScheduleScript = /usr/libexec/backup-utils/scheduleWarning.pl

[LDAP]
Server = ldaps://ldapm.tombstone.ch
Port = 636
Username = cn=Manager,dc=stoney-cloud,dc=org
Password = <PASSWORD>
AccountBase = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
</pre>

==== Cronjobs ====
As you can pass the notification flag to the scripts, you can call the quota script say all 10 minutes. This makes sense if followed the configuration section, as the writeAccountSize.pl script writes the quota values to the LDAP backend which will then be visible in the selfcare webinterface. Like that you have a more or less up to date quota representation in the selfcare webinterface. On the other side, you don't want to send notification mails to the user every 10 minutes. It might be enough to send them once a day, so the cronjobs may look like:
<pre>
# Check backups
15 12 * * * /usr/libexec/backup-utils/checkBackups.pl --schedule --quota --notify

# Write quota values every 10 minutes
*/10 * * * * /usr/libexec/backup-utils/checkBackups.pl --quota
</pre>

== ResellerBackupBilling.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeDate.pl</code> by the <code>sys-apps/sst-backup-utils</code> package. The pod documentation says all what needs to be said about this script.
* Pod documentation
<pre>
NAME
ResellerBackupBilling.pl

DESCRIPTION
This script processes the reseller with the passed UID and creates a
very simplistic backup-billing overview which then is sent to the
address specified in the configuration file. The billing overview
contains all backup accounts which belong to the given reseller as well
as their quota. According to the billing plan specified in the
configuration file, the script also calculates the price for each backup
account.

The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

OPTIONS
--reseller/-r UID
Process the reseller with this UID

--debug/-d
Turn on debug mode

--help/-h
Display this help

USAGE
./ResellerBackupBilling.pl --reseller UID [--debug] [--help]

./ResellerBackupBilling.pl --reseller 2000000
This processes the reseller with the UID 200000 and sends the
billing overview to the address specified in the configuration file

CREATED
2014-01-24 pat.klaey@stepping-stone.ch created

VERSION
2014-01-24 pat.klaey@stepping-stone.ch created

INCORPORATED CODE
Incorporated code with use:

warnings;
strict;
Getopt::Long;
PerlUtil::LDAPUtil;
PerlUtil::Logging;
PerlUtil::Mail;
Number::Format;
File::Basename;
Cwd 'abs_path';
</pre>
=== Configuration ===
You have to configure basically three things:
# How to access the LDAP directory (similar to the other backup-util scripts)
# Define a pricing schema
#* Define a base price for an account
#* Define a GB price
#* The total price for each account will finall be: <code>base price + ( quota in GB * GB price )</code>
# How to send the mail
#* You need to enter a valid (outgoing) mail server and corresponding port
#* User and password to authenticate on the mail server
#* A valid recipient (typically the company’s backoffice address) and sender

/etc/backup-utils/ResellerBackupBilling.conf
<pre>
[LDAP]
Server = ldaps://ldapm.tombstone.ch
Port = 636
Username = cn=Manager,dc=stoney-cloud,dc=org
Password = <Password>
AccountBase = ou=accounts,ou=backup,ou=services,dc=stoney-cloud,dc=org
CustomerBase = ou=customers,dc=stoney-cloud,dc=org
ResellerBase = ou=reseller,dc=stoney-cloud,dc=org

[Pricing]
AccountBasePrice = 5.00
AccountGBPrice = 0.50

[Mail]
Server = <Mail-Server>
Port = 587
Username = <Sender-Email-Address>
Password = <Password>
To = <Backoffice>
From = Billing Script <E-Mail-Address>
</pre>

== writeDate.pl ==
This script is installed to <code>/usr/libexec/backup-utils/writeDate.pl</code> by the <code>sys-apps/sst-backup-utils</code> package. This is a very simple script, it simply writes the current date and time to a file on the backup server before the rsnapshots rotates the backup. This date is used by the Sepiola Online Backup Client to display the iterations and their dates.
* Pod documentation:
<pre>
NAME
writeDate.pl

DESCRIPTION
This script writes the current date and time into the file for each
backup before the rsnapshots rotates the backup. This information is
used by the Sepiola Online Backup Client.

The configuration file for this script is stored under
/etc/backup-utils/writeDate.conf

The script uses syslog for logging purposes.

Command Line Interface (CLI) parameters:

-C configfile
The configuration file.

-U uid
The user id.

-d debug
Turns the debug mode on.

-h help
This online help.

USAGE
writeDate.pl [-C configuration_file] [-U uid] [-d debug] [-h help]

CREATED
2007-09-16 michael.eichenberger@stepping-stone.ch created

VERSION
2013-09-01 michael.eichenberger@stepping-stone.ch updated to reflect
changes in the new backup environment

2007-09-16 michael.eichenberger@stepping-stone.ch created

INCORPORATED CODE
Incorporate code with use:

warnings;
strict;
Config::IniFiles;
Getopt::Std;
Sys::Syslog;
</pre>

=== Configuration ===
/etc/backup-utils/writeDate.conf
<pre>
[Global]
BACKUP_DIRECTORY = /incoming
BACKUP_BACKUP_TIME_FILE = /.sepiola_backup/backupTime

[Syslog]
SYSLOG = rsnapshot
</pre>

== rsnapshot wrapper bash scripts ==
There are two rsnapshot wrapper scripts (these are bash scripts), they are installed by the <code>sys-apps/sst-backup-utils</code> package:
* <code>/usr/libexec/backup-utils/rsnapshotPreExecWrapper.sh</code>
** This script is executed before the rsnapshot process and simply calls the [[stoney_backup:_Server_set-up#writeDate.pl | writeDat.pl ]] script.
* <code>/usr/libexec/backup-utils/rsnapshotPostExecWrapper.sh</code>
** This script is executed after the rsnapshot process and simply calls the [[stoney_backup:_Server_set-up#writeAccountSize.pl | writeAccountSize.pl ]] script.

'''Note:''' These scripts do not need any configuration.

= Links =
* [http://www.openldap.org/ OpenLDAP], an open source implementation of the Lightweight Directory Access Protocol.
* [http://arthurdejong.org/nss-pam-ldapd/ nss-pam-ldapd], a Name Service Switch (NSS) module that allows your LDAP server to provide user account, group, host name, alias, netgroup, and basically any other information that you would normally get from /etc flat files or NIS.
* [http://www.gentoo.org/doc/de/ldap-howto.xml Gentoo Leitfaden zur OpenLDAP Authentifikation].
* [http://wiki.gentoo.org/wiki/Centralized_authentication_using_OpenLDAP Centralized authentication using OpenLDAP].
* [https://code.google.com/p/openssh-lpk/source/browse/trunk/schemas/openssh-lpk_openldap.schema openssh-lpk_openldap.schema] OpenSSH LDAP Public Keys.
* [http://sourceforge.net/projects/linuxquota/ linuxquota] Linux DiskQuota.
* [http://www.rsnapshot.org/ rsnapshot], a remote filesystem snapshot utility, based on rsync.
* [http://olivier.sessink.nl/jailkit/ Jailkit], set of utilities to limit user accounts to specific files using chroot() and or specific commands. Also includes a tool to build a chroot environment.
* [http://www.busybox.net/ Busybox] BusyBox combines tiny versions of many common UNIX utilities into a single small executable. Useful to reduce the number of files (and thus the complexity) when building a chroot.

[[Category:stoney backup]]

stoney core: People Resource - REST API

2014-06-08T10:21:59Z

Chrigu:

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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 informations 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 informations.

==== 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>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>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 informations.
|
|
|
|<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 informations 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T10:18:19Z

Chrigu: /* People collection retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 informations 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 informations.

==== 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>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>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 informations.
|
|
|
|<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 informations 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T10:16:43Z

Chrigu: /* Person element retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 customer resource must belong 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 informations 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 informations.

==== 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>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>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 informations.
|
|
|
|<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 informations 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T10:11:28Z

Chrigu: /* Person element retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 customer resource must belong 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 informations 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 informations.

==== 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>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>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>belongsToReseller</code>
|integer
|yes
|The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] location URI 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]] UID the person belongs to
|
|@TODO add regex
|
|<source lang="javascript">"belongsToCustomerId": 4000002</source>

|-
|<code>belongsToCustomer</code>
|integer
|yes
|The [[stoney_core:_Customers_Resource_-_REST_API|customer's]] location URI the person belongs to.
|
|@TODO add regex
|
|<source lang="javascript">"belongsToResellerId": 4000000</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 informations.
|
|
|
|<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 informations 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T10:00:35Z

Chrigu: /* Person partly update request message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 customer resource must belong 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 informations 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 informations.

==== 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>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>belongsToResellerId</code>
|integer
|yes
|The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] identification number the customer resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"belongsToResellerId": 4000000</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>

|-
|[[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 informations.
|
|
|
|<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 informations 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:57:23Z

Chrigu: /* Person element retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 customer resource must belong 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 informations 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 informations.

==== 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>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>belongsToResellerId</code>
|integer
|yes
|The [[stoney_core:_Resellers_Resource_-_REST_API|reseller's]] identification number the customer resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"belongsToResellerId": 4000000</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>

|-
|[[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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:51:50Z

Chrigu: /* Person element retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 customer resource must belong 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 informations 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 informations.

==== 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>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:44:37Z

Chrigu: /* People collection retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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 customer resource must belong 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 informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:40:33Z

Chrigu: /* People collection retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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>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>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:36:07Z

Chrigu: /* People collection retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:34:57Z

Chrigu: /* People collection retrieval response message */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: Search Resource - REST API

2014-06-08T09:33:07Z

Chrigu: Undo revision 3595 by Chrigu (talk)

Also visit [[stoney core: Search Resource Mapping (REST - LDAP)]] and [[stoney core: Global Searches]].

= Overview =
The search resource provides a full text search over all the available resources. The available resources are:
* The main framework called [[:Category:stoney core|stoney core]] is responsible for shared functionality.
* The [[:Category:Self-Service Modules|Self-Service Modules]] expand the initial stoney cloud functionality.

A search could look as follows:
* <code>https://api.example.com/v1/search?q=fluffy+dragon&entries=15</code>.

The following rules apply:
* The minimum number of characters for the query are 3.
* Number of entries returned '''per''' object type:
** Default: 5
** Maximum: 15 (can be raised by '''entries''' get parameter)
* The attributes returned for each individual resource are presently the same as when querying the corresponding resource collection.

= stoney core: search resource methods =
As described above, each resource has its own search methods. The current stoney core resources are:
* [[stoney core: Resellers Resource - REST API]]
* [[stoney core: Customers Resource - REST API]]
* [[stoney core: People Resource - REST API]]

The following special resources don't have additional search methods:
* [[stoney core: Authentication Resource - REST API]]

== Global Search (GET) ==
Also visit [[stoney core: Search Resource Mapping (REST - LDAP)]] and [[stoney core: Global Searches]].

To form a global fulltext search (over all resources), append the url query parameter '''q''' with the desired search text: <code>https://api.example.com/v1/search?q=example</code>.

=== Global Search 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/search?q=example 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>

|}

=== Global Search 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
</pre>

|-
| [[#global_search_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

==== Global Search Response Message Body ====
{| class="wikitable sortable" style="width: 100%;" id="global_search_response_object"
|-
|+ align="top" style="text-align:left;"|Global Search Response Object
! Parameter name
! Data type
! Mandatory
! Description
! Valid content
! [http://www.pcre.org/ PCRE]
! Default value
! Example

|-
|
|ôbject
|no
| An object containing an array with one or more resource collection objects. See [[stoney_core:_Resellers_Resource_-_REST_API#reseller_collection_array_element_object | Reseller Collection Array Element Object]] for a concrete example.
|
|
|
|<source lang='javascript'>
{
"resellers":
{
"resources":
[
{ "id": 4000000,
"location": "https://api.example.com/v1/resellers/4000000",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller Ltd",
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern"
},
{ "id": 4000001,
"location": "https://api.example.com/v1/resellers/4000001",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller No 2 Ltd",
"countryCode": "CH",
"postalCode": "8004",
"localityName": "Zürich"
}
],
"location": "https://api.example.com/v1/resellers/?q=example"
},
"customers":
{
"resources":
[
{ "id": 5000000,
"location": "https://api.example.com/v1/customers/5000000",
"isCompany": true,
"isActive": true,
"customerName": "Example Customer Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000
},
{ "id": 5000001,
"location": "https://api.example.com/v1/customers/5000001",
"isCompany": false,
"isActive": true,
"customerName": "Peter Example"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000001
}
],
"location": "https://api.example.com/v1/customers/?q=example"
},
"people":
{
"resources":
[
{ "id": 6000000,
"location": "https://api.example.com/v1/people/6000000",
"isActive": true,
"givenName": "Peter",
"surname": "Example"
"customerName": "Example Customer Ltd",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
{ "id": 6000001,
"location": "https://api.example.com/v1/people/6000001",
"isActive": true,
"givenName": "Thomas",
"surname": "Example"
"customerName": "Example Customer Ltd",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
],
"location": "https://api.example.com/v1/people/?q=example"
},
...
}
</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 informations.
|
|
|
|<source lang="javascript">error { /* ... */ }</source>

|}

== Global Search Response Object (stoney core: Resellers Resource) ==
The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_Resellers_Resource.29 | Global Search Response Object (stoney core: Resellers Resource)]].

Resource collection object for the stoney core: Resellers Resource.
<source lang='javascript'>
"resellers":
{
"resources":
[
{ "id": 4000000,
"location": "https://api.example.com/v1/resellers/4000000",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller Ltd",
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern"
},
{ "id": 4000001,
"location": "https://api.example.com/v1/resellers/4000001",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller No 2 Ltd",
"countryCode": "CH",
"postalCode": "8004",
"localityName": "Zürich"
}
],
"location": "https://api.example.com/v1/resellers/?q=example"
},
</source>

== Global Search Response Object (stoney core: Customers Resource) ==
The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_Customers_Resource.29 | Global Search Response Object (stoney core: Customers Resource)]].

Resource collection object for the stoney core: Customers Resource.
<source lang='javascript'>
"customers":
{
"resources":
[
{ "id": 5000000,
"location": "https://api.example.com/v1/customers/5000000",
"isCompany": true,
"isActive": true,
"customerName": "Example Customer Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000
},
{ "id": 5000001,
"location": "https://api.example.com/v1/customers/5000001",
"isCompany": false,
"isActive": true,
"customerName": "Peter Example"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000001
}
],
"location": "https://api.example.com/v1/customers/?q=example"
},
</source>

== Global Search Response Object (stoney core: People Resource) ==
The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_People_Resource.29 | Global Search Response Object (stoney core: People Resource)]].

Resource collection object for the stoney core: People Resource.
<source lang='javascript'>
"people":
{
"resources":
[
{ "id": 6000000,
"location": "https://api.example.com/v1/people/6000000",
"isActive": true,
"givenName": "Peter",
"surname": "Example"
"customerName": "Example Customer Ltd",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
{ "id": 6000001,
"location": "https://api.example.com/v1/people/6000001",
"isActive": true,
"givenName": "Thomas",
"surname": "Example"
"customerName": "Example Customer Ltd",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
],
"location": "https://api.example.com/v1/people/?q=example"
},
</source>

[[Category: REST API]][[Category:stoney core]]

stoney core: Search Resource - REST API

2014-06-08T09:31:12Z

Chrigu: /* Global Search Response Message Body */

Also visit [[stoney core: Search Resource Mapping (REST - LDAP)]] and [[stoney core: Global Searches]].

= Overview =
The search resource provides a full text search over all the available resources. The available resources are:
* The main framework called [[:Category:stoney core|stoney core]] is responsible for shared functionality.
* The [[:Category:Self-Service Modules|Self-Service Modules]] expand the initial stoney cloud functionality.

A search could look as follows:
* <code>https://api.example.com/v1/search?q=fluffy+dragon&entries=15</code>.

The following rules apply:
* The minimum number of characters for the query are 3.
* Number of entries returned '''per''' object type:
** Default: 5
** Maximum: 15 (can be raised by '''entries''' get parameter)
* The attributes returned for each individual resource are presently the same as when querying the corresponding resource collection.

= stoney core: search resource methods =
As described above, each resource has its own search methods. The current stoney core resources are:
* [[stoney core: Resellers Resource - REST API]]
* [[stoney core: Customers Resource - REST API]]
* [[stoney core: People Resource - REST API]]

The following special resources don't have additional search methods:
* [[stoney core: Authentication Resource - REST API]]

== Global Search (GET) ==
Also visit [[stoney core: Search Resource Mapping (REST - LDAP)]] and [[stoney core: Global Searches]].

To form a global fulltext search (over all resources), append the url query parameter '''q''' with the desired search text: <code>https://api.example.com/v1/search?q=example</code>.

=== Global Search 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/search?q=example 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>

|}

=== Global Search 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
</pre>

|-
| [[#global_search_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

==== Global Search Response Message Body ====
{| class="wikitable sortable" style="width: 100%;" id="global_search_response_object"
|-
|+ align="top" style="text-align:left;"|Global Search Response Object
! Parameter name
! Data type
! Mandatory
! Description
! Valid content
! [http://www.pcre.org/ PCRE]
! Default value
! Example

|-
|
|ôbject
|no
| An object containing an array with one or more resource collection objects. See [[stoney_core:_Resellers_Resource_-_REST_API#reseller_collection_array_element_object | Reseller Collection Array Element Object]] for a concrete example.
|
|
|
|<source lang='javascript'>
{
"resellers":
{
"resources":
[
{ "id": 4000000,
"location": "https://api.example.com/v1/resellers/4000000",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller Ltd",
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern"
},
{ "id": 4000001,
"location": "https://api.example.com/v1/resellers/4000001",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller No 2 Ltd",
"countryCode": "CH",
"postalCode": "8004",
"localityName": "Zürich"
}
],
"location": "https://api.example.com/v1/resellers/?q=example"
},
"customers":
{
"resources":
[
{ "id": 5000000,
"location": "https://api.example.com/v1/customers/5000000",
"isCompany": true,
"isActive": true,
"customerName": "Example Customer Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000
},
{ "id": 5000001,
"location": "https://api.example.com/v1/customers/5000001",
"isCompany": false,
"isActive": true,
"customerName": "Peter Example"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000001
}
],
"location": "https://api.example.com/v1/customers/?q=example"
},
"people":
{
"resources":
[
{ "id": 6000000,
"location": "https://api.example.com/v1/people/6000000",
"isActive": true,
"givenName": "Peter",
"surname": "Example",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
{ "id": 6000001,
"location": "https://api.example.com/v1/people/6000001",
"isActive": true,
"givenName": "Thomas",
"surname": "Example",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
],
"location": "https://api.example.com/v1/people/?q=example"
},
...
}
</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 informations.
|
|
|
|<source lang="javascript">error { /* ... */ }</source>

|}

== Global Search Response Object (stoney core: Resellers Resource) ==
The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_Resellers_Resource.29 | Global Search Response Object (stoney core: Resellers Resource)]].

Resource collection object for the stoney core: Resellers Resource.
<source lang='javascript'>
"resellers":
{
"resources":
[
{ "id": 4000000,
"location": "https://api.example.com/v1/resellers/4000000",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller Ltd",
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern"
},
{ "id": 4000001,
"location": "https://api.example.com/v1/resellers/4000001",
"isCompany": true,
"isActive": true,
"resellerName": "Example Reseller No 2 Ltd",
"countryCode": "CH",
"postalCode": "8004",
"localityName": "Zürich"
}
],
"location": "https://api.example.com/v1/resellers/?q=example"
},
</source>

== Global Search Response Object (stoney core: Customers Resource) ==
The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_Customers_Resource.29 | Global Search Response Object (stoney core: Customers Resource)]].

Resource collection object for the stoney core: Customers Resource.
<source lang='javascript'>
"customers":
{
"resources":
[
{ "id": 5000000,
"location": "https://api.example.com/v1/customers/5000000",
"isCompany": true,
"isActive": true,
"customerName": "Example Customer Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000
},
{ "id": 5000001,
"location": "https://api.example.com/v1/customers/5000001",
"isCompany": false,
"isActive": true,
"customerName": "Peter Example"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000001
}
],
"location": "https://api.example.com/v1/customers/?q=example"
},
</source>

== Global Search Response Object (stoney core: People Resource) ==
The logic is described on the [[stoney core: Search Resource Mapping (REST - LDAP)]] page under the chapter [[stoney_core:_Search_Resource_Mapping_(REST_-_LDAP)#Global_Search_Response_Object_.28stoney_core:_People_Resource.29 | Global Search Response Object (stoney core: People Resource)]].

Resource collection object for the stoney core: People Resource.
<source lang='javascript'>
"people":
{
"resources":
[
{ "id": 6000000,
"location": "https://api.example.com/v1/people/6000000",
"isActive": true,
"givenName": "Peter",
"surname": "Example"
"customerName": "Example Customer Ltd",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
{ "id": 6000001,
"location": "https://api.example.com/v1/people/6000001",
"isActive": true,
"givenName": "Thomas",
"surname": "Example"
"customerName": "Example Customer Ltd",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 5000000
},
],
"location": "https://api.example.com/v1/people/?q=example"
},
</source>

[[Category: REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:24:59Z

Chrigu: /* People collection retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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>

|-
| [[#person_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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:23:58Z

Chrigu: /* People collection retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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>

|-
| [[#person_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="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:23:31Z

Chrigu: /* People collection retrieval response message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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>

|-
| [[#person_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="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:15:25Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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 informations.
|
|
|
|<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>

|-
| [[#person_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="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:14:23Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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 informations.
|
|
|
|<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>

|-
| [[#person_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="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:11:39Z

Chrigu: /* People retrieval (GET) */

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 (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 [[: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 informations.
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.
|
|@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 informations.
|
|
|
|<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>

|-
| [[#person_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="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:06:36Z

Chrigu: /* Search (with filter) */

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 (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 [[: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 informations.
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.
|
|@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 informations.
|
|
|
|<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]].

==== Person 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:05:48Z

Chrigu: /* Sort */

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 (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 [[: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 informations.
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.
|
|@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 informations.
|
|
|
|<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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-08T09:03:46Z

Chrigu: /* Person retrieval (GET) */

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 (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 [[: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 informations.
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.
|
|@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 informations.
|
|
|
|<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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T15:12:22Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T15:04:47Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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>employeeOfUID</code>
|array
|yes
|The UID(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">
"employeeOfUID": [
4000002,
4001003,
4002004
]
</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T15:04:03Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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>employeeOfUID</code>
|array
|yes
|The UID(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
|@TODO add regex
|
|<source lang="javascript">"
employeeOfUID": [
4000002,
4001003,
4002004
]
</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T14:51:52Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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>

|}

=== 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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T14:50:41Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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>

|}

{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>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>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"
|-
|+ align="top" style="text-align:left;"|shippingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|
|@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.
|
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>

|-
|<code>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T14:50:20Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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>

|}

{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>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>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"
|-
|+ align="top" style="text-align:left;"|shippingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|
|@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.
|
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>

|-
|<code>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T14:49:16Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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">"id": 4000002</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>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>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"
|-
|+ align="top" style="text-align:left;"|shippingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|
|@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.
|
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>

|-
|<code>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T14:29:43Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000001</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000002</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>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>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"
|-
|+ align="top" style="text-align:left;"|shippingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|
|@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.
|
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>

|-
|<code>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T14:27:11Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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>

sstTimeZoneOffset

|-
|<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 reseller identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000001</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000002</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>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>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"
|-
|+ align="top" style="text-align:left;"|shippingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|
|@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.
|
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>

|-
|<code>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-05T14:25:54Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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
|<[http://www.loc.gov/standards/iso639-2/php/code_list.php ISO 639-1 Code]>-<[http://www.iso.org/iso/english_country_names_and_code_elements ISO 3166-1-alpha-2 code]>
|
|
|<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>

sstTimeZoneOffset

|-
|<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 reseller identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000001</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000002</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>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>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"
|-
|+ align="top" style="text-align:left;"|shippingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|
|@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.
|
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>

|-
|<code>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]

stoney core: People Resource - REST API

2014-06-04T15:09:28Z

Chrigu: /* Person creation request message body */

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 (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 [[: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 informations.
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.
|
|@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
|<[http://www.loc.gov/standards/iso639-2/php/code_list.php ISO 639-1 Code]>-<[http://www.iso.org/iso/english_country_names_and_code_elements ISO 3166-1-alpha-2 code]>
|
|
|<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>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000001</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the newly created person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000002</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="billingAddress_object"
|-
|+ align="top" style="text-align:left;"|billingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>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>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</source>

|}

{| class="wikitable sortable" style="width: 100%;" id="shippingAddress_object"
|-
|+ align="top" style="text-align:left;"|shippingAddress Object
!Parameter name
!Data type
!Mandatory
!Description
!Valid content
![http://www.pcre.org/ PCRE]
!Default value
!Example

|-
|<code>organizationName</code>
|string
|no
|The name of the organization.
|
|@TODO: Add regex
|
|<source lang="javascript">"organizationName": "Person Ltd."</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>givenName</code>
|string
|yes
|The given name (first name or forename) of the address holder.
|
|@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.
|
|@TODO: Add regex
|
|<source lang="javascript">"surname": "Surname"</source>

|-
|<code>postalAddress</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalAddress": ""</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|<code>preferredLanguage</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"preferredLanguage": ""</source>

|-
|<code>mail</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mail": ""</source>

|-
|<code>telephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"telephoneNumber": ""</source>

|-
|<code>mobileTelephoneNumber</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"mobileTelephoneNumber": ""</source>

|-
|<code>websiteURL</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"websiteURL": ""</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 informations.
|
|
|
|<source lang="javascript">"error": { /* ... */ }</source>

|}

== Person retrieval (GET) ==
=== Person 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=personName,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 '''personName''') with the desired search text: <code>https://api.example.com/v1/people?personName=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 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>

|}

==== Person 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>

|-
| [[#person_collection_retrieval_response_object|Response body]]
| JSON object
| <source lang="javascript">{ ... }</source>

|}

====== Person collection retrieval response message body ======
{| class="wikitable sortable" style="width: 100%;" id="person_collection_retrieval_response_object"
|-
|+ align="top" style="text-align:left;"|Person 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",
"isCompany": true,
"isActive": true,
"personName": "Person Ltd"
"countryCode": "CH",
"postalCode": "3012",
"localityName": "Bern",
"belongsToResellerID": 4000000,
"belongsToCustomerID": 4000001
},
{
/* ... */
}
]
</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 informations.
|
|
|
|<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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Person Ltd"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": "CH"</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": "3012"</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": "Bern</source>

|-
|<code>belongsToResellerID</code>
|integer
|yes
|The reseller identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|-
|<code>belongsToCustomerID</code>
|integer
|yes
|The customer identification number the person resource must belong to.
|
|@TODO add regex
|
|<source lang="javascript">"id": 4000000</source>

|}

=== Person element retrieval (GET) ===
To retrieve an existing person and fetch the informations 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 informations.

==== 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>isCompany</code>
|boolean
|yes
|<code>true</code> if the person represents a company, <code>false</code> if it's an individual person.
|<code>true</code> or <code>false</code>
|
|
|<source lang="javascript">"isCompany": true</source>

|-
|<code>isActive</code>
|boolean
|yes
|
|<code>true</code> or <code>false</code>
|
|<code>true</code>
|<source lang="javascript">"isActive": true</source>

|-
|<code>personName</code>
|string
|yes
|The person's display name. Mostly the same as the <code>organizationName</code> or the <code>givenName</code> and <code>surname</code> out of the [[#billingAddress_object|billingAddress object]], but can also be the name of a brand.
|
|
|
|<source lang="javascript">"personName": "Super-duper Hosting"</source>

|-
|<code>countryCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"countryCode": ""</source>

|-
|<code>postalCode</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"postalCode": ""</source>

|-
|<code>localityName</code>
|string
|yes
|
|
|@TODO: Add regex
|
|<source lang="javascript">"localityName": ""</source>

|-
|[[#billingAddress_object|<code>billingAddress</code>]]
|object
|yes
|An object holding the billing address informations for the given person. Refer to the [[#billingAddress_object|billingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"billingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|[[#shippingAddress_object|<code>shippingAddress</code>]]
|object
|no
|An object holding the shipping address informations for the given person. Refer to the [[#shippingAddress_object|shippingAddress object table]] for more informations.
|
|
|
|<source lang="javascript">
"shippingAddress":
{
"organizationName": "Person Ltd.",
"gender": 'm',
"givenName": "Name",
"surname": "Surname",
"postalAddress": "Street Number",
"countryCode": "CH",
"postalCode": "1234",
"localityName": "Locality",
"preferredLanguage": "en-GB",
"mail": "name.surname@example.com",
"telephoneNumber": "+41 00 000 00 00",
"mobileTelephoneNumber": "+41 00 000 00 00",
"websiteURL": "https://www.example.com/"
}
</source>

|-
|<code>people</code>
|string
|yes
|The location URI of the people belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"people": "https://api.example.com/v1/people/5000001/people"</source>

|-
|<code>employees</code>
|string
|yes
|The location URI of the employees belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"employees": "https://api.example.com/v1/people/5000001/employees"</source>

|-
|<code>users</code>
|string
|yes
|The location URI of the users belonging to this person resource.
|@TODO add link to URI RFC
|
|
|<source lang="javascript">"users": "https://api.example.com/v1/people/5000001/users"</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 informations.
|
|
|
|<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 informations 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]].
@TODO: Add example.

=== 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 informations 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 informations 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]]

[[Category:REST API]][[Category:stoney core]]