$Id: API 43480 2015-06-19 14:35:05Z wsl $
$URL: https://svn.uvt.nl/its-id/trunk/sources/kiki/doc/API $

1)	Authenticatie gaat met een SSL-certificaat: de servercertificaten die
	DigiCert uitgeeft zijn ook als clientcertificaat te gebruiken. Pak dus een
	willekeurig servercertificaat en laat me de CN weten, dan voeg ik je toe
	aan het ACL-lijstje.

2)	Het doen van verzoeken gaat via het ReST-principe. Elke URL
	representeert een stukje data (een persoon, een lijst) en met het juiste
	HTTP-verzoek kun je die data manipuleren. Je hebt dus een HTTP-library
	nodig die je toestaat de request method en request body aan te passen.

	Als er iets mis is met het verzoek, wordt dat (ook) via de HTTP status
	code gecommuniceerd. Controleer die dus altijd. 2XX is goed, 4XX en 5XX
	niet.

3)	De data wordt via JSON verscheept, zowel voor requests als voor
	antwoorden. JSON snapt key-value-paren (“objects”, het JSON-equivalent
	van Perl hashes), lijstjes, strings, getallen, booleans en null.

	De voorbeelden hieronder heb ik geïndenteerd, de daadwerkelijke input
	en output zijn zonder whitespace, er zit zelfs geen newline aan het
	eind.

4)	De blacklist kun je opvragen via GET https://pichu.uvt.nl/kiki/blacklist
	en geeft output van de vorm:

	{
		"blacklist": [
			"foo@uvt.nl",
			"bar@uvt.nl",
			"B.Ar@uvt.nl",
			"quux@tias.edu",
			...
		]
	}

	Deze lijst bevat alle gebruikte namen in alle bekende domeinen, zowel
	functioneel als persoonlijk.

5)	De lijst met alle geregistreerde personen kun je opvragen met
	GET https://pichu.uvt.nl/kiki/persons en geeft output van de vorm:

	{
		"persons": [
			{
				"anr": 780251,
				"mailbox": "anton@mailbox.uvt.nl",
				"labels": [
					"Anton.Sluijtman@uvt.nl",
					"anton@uvt.nl"
				]
			},
			{
				"anr": 210882,
				"mailbox": "jurgenvd@email.campus.uvt.nl",
				"labels": [
					"Jurgen.vanDijk@uvt.nl",
					"J.G.H.vanDijk@uvt.nl",
					"JurgenvanDijk@uvt.nl",
					"jurgenvd@uvt.nl",
				]
			},
			...
		]
	}

6)	Een enkele persoon ophalen kan met
	GET https://pichu.uvt.nl/kiki/persons/<anr> en geeft output van de vorm:

	{
		"person": {
			"anr": 488937,
			"mailbox": "wsl@homsar.uvt.nl",
			"labels": [
				"W.S.L.Dankers@uvt.nl",
				"wsl@uvt.nl"
			]
		}
	}

	Het eerst genoemde label is ‘canonical’, oftewel het primaire adres voor
	deze persoon.

7)	Een persoon aanmaken of bijwerken doe je met
	PUT https://pichu.uvt.nl/kiki/persons/<anr> en request data van de vorm:

	{
		"mailbox": "pietje@mailbox.uvt.nl",
		"labels": [
			"P.Ietje@uvt.nl",
			"pietje@uvt.nl"
		]
	}

	Waarbij ‘pietje’ het uid is van de user. Let dus op dat je ook het uid als
	label provisiont. De ‘mailbox’ is de plek waar de e-mail afgeleverd moet
	worden. Dat zal typisch een Exchange of Google mailbox zijn.

	Je krijgt dan output van de vorm:

	{
		"previous": {
			"anr": 123456,
			"mailbox": "pietje@mailbox.uvt.nl",
			"labels": [
				"P.Ietje@uvt.nl",
				"pietje@uvt.nl"
			]
		},
		"notes": {
			"mailbox": [
				"ok",
				"mailbox",
				"pietje@mailbox.uvt.nl"
			],
			"update": [
				"ok",
				"stored"
			],
			"labels": [
				[
					"ok",
					"unchanged",
					"P.Ietje@uvt.nl"
				],
				[
					"ok",
					"unchanged",
					"pietje@uvt.nl"
				]
			]
		},
		"person": {
			"anr": 123456,
			"mailbox": "pietje@mailbox.uvt.nl",
			"labels": [
				"P.Ietje@uvt.nl",
				"pietje@uvt.nl"
			]
		}
	}

	Waarbij "previous" en "person" de gegevens voor en na zijn, en "notes"
	feedback geeft over eventuele problemen. Voor een globale check of de
	transactie gelukt is, controleer je notes.update[0]. Die kan de waarden
	"ok" of "error" bevatten. Indien notes.update[1] bestaat, geeft die meer
	informatie over de reden van het falen. Daarbij kun je vanuit de API
	alleen de volgende waarde krijgen:

	"invalid-anr": de ANR die je probeert aan te maken is ongeldig

	Bestaat notes.update[1] niet, dan is er iets mis met de mailbox of met
	de labels. Fouten voor de mailbox kunnen zijn:

	"missing-address": als de mailbox ontbreekt in het verzoek
	"mailbox-modified": als de persoon al een mailbox had
	"invalid-address": als het opgegeven adres niet aan RFC 2822 voldoet
	"internal-domain": als het adres een domein heeft dat intern is
	"invalid-domain": als het opgegeven domein geen e-mail kan ontvangen

	Fouten voor labels kunnen zijn:

	"localpart-too-long": het gedeelte voor de @ is langer dan 64 karakters
	"address-exists": het adres bestaat al voor een andere persoon/alias
	"invalid-localpart": het gedeelte voor de @ bevat niet-toegestane
		(combinaties van) karakters
	"unknown-domain": voor dit domein verwerken wij geen e-mail
	"invalid-address": dit ziet er niet eens uit als een e-mailadres

8)	De gegevens verwijderen voor een persoon kan met
	DELETE https://pichu.uvt.nl/kiki/persons/<anr> en geeft output van de vorm:


	{
		"person": {
			"anr": 123456,
			"mailbox": "pietje@mailbox.uvt.nl",
			"labels": [
				"P.Ietje@uvt.nl",
				"pietje@uvt.nl"
			]
		},
		"note": [
			"ok",
			"removed"
		]
	}

	Waarbij note[0] weer de status aangeeft, en note[1] het ‘waarom’.
	Aangezien niet-bestaande ANRs triviaal “verwijderd” kunnen worden en er
	verder niet echt iets in een verwijderverzoek zit dat ‘fout’ kan zijn,
	hoef je alleen de HTTP-statuscode te controleren.
