Wiki
Clone wikiOCAPI / nl_index
INDEX
Inleiding
OCAPI is ontstaan als een extensie op Opencart waarbij het de bedoeling is de oorspronkelijke code niet te veranderen en gebruik te maken van de mogelijkheden (en user interfaces) welke deze webshop biedt.
Hoewel de gegevens/database-schema's in naamgeving en structuur totaal niet overeenkomen met dge, wordt een groot deel van de benodigde gegevens geconverteerd
De API zelf is geschikt om zowel XML als JSON te verwerken, waarbij standaard HTTP methods en status codes worden gebruikt. Echter, zijn er concessies toegevoegd omdat het dge platform, ten tijde van de ontwikkeling, niet beschikte over volledig functionele HTTP mogelijkheden.
Het dge pakket communiceert nu (nog) volledig in XML, terwijl de API ook geschikt is voor het efficiëntere JSON. Default wordt een XML response gegeven, echter door gebruik te maken van de extensie .JSON wordt JSON geforceerd. De extensie is altijd optioneel (niet noodzakelijk)
http://[mijnapi.url]/v1/[controller]/[id][.xml] http://[mijnapi.url]/v1/[controller]/[id][.json]
Wellicht dat ook in de toekomst het dge-pakket via XML blijft communiceren.
Dezelfde API wordt ook gebruikt voor het importeren van ez-base gegevens, echter wel middels JSON.
De HTTP methods welke door het pakket gebuikt worden zijn:
- GET
- POST
Een DELETE request wordt uitgevoerd door bij een GET request een delete commando in de URL mee te geven;
http://[mijnapi.url]/v1/[controller]/delete/[id][.xml|.json]
Echter een DELETE http request geeft hetzelfde resultaat.
HTTP method delete http://[mijnapi.url]/v1/[controller]/[id][.xml|.json]
Een PUT request wordt hetzelfde als een POST request afgehandeld.
Authenticatie:
Bij iedere request worden tokens in de header mee gestuurd ter authenticatie van de gebruiker. Deze token-combinatie is 24 uur geldig, daarna dient de combinatie vergeten te worden (valideert nooit meer).
Het is niet noodzakelijk iedere request iedere keer te controleren. Indien een onbekende combinatie wordt ontvangen dan kan een eenmalig controle voldoende zijn. De combinatie is daarna 24 uur geldig. Na 24 uur is de combinatie ongeldig (en dient niet meer ge-accepteerd te worden).
De tokens worden meegegeven in de header:
x-auth-token: e3a6a1fc0bf3e1f0c5dcb801caca5fb3 x-service-token: 555c7f149178099205edcc30
OCAPI / App / Helpers / AclClient.php
STATUS CODES
Er wordt getracht de standaard HTTP statuscodes te gebruiken.
Dus indien iets ge-update of opgehaald dient te worden maar niet bestaat dan wordt een 404 geretourneerd.
Bij een succes wordt altijd een 200 geretourneerd (bij een succesvolle POST dus ook). Codes in de 3XX serie worden nooit geretourneerd (niet opgevolgd).
En 401/403 wanneer de authenticatie failed.
ERRORS
Per controller POST, in de code, worden alle mogelijke waarden gecontroleerd. De controle is in te zien op Bitbucket.
De mogelijke waarden en limitaties zijn ontleent uit Opencart en daarop aangepast. Indien ongeldige data wordt ontvangen dan volgt altijd een 4XX error (406) met een repsonse waarin duidelijk de veldnaam is vermeld waar de fout heeft plaatsgevonden.
HTTP/1.1 406 Not Acceptable Date: Fri, 22 May 2015 06:55:05 GMT Server: Apache/2.2.15 (CentOS) X-Powered-By: OC Dge Driver (v2) Transfer-Encoding: chunked Connection: close Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="UTF-8"?> <response> <error> <ERRNO>E001</ERRNO> <message>Post Field Value</message> <description>name</description> </error> </response>
Een response als deze (met dezelfde) is aan te raden, ook voor andere fouten. Vanuit het pakket is dan duidelijk te achterhalen waar eventuele fouten plaatsvinden. In het pakket worden ERRORS gelogged, maar zijn niet gelijk een reden om de functionaliteit verder te blokkeren.
XSD
Er zijn een aantal XSD beschikbaar hier welke gebruikt worden in het pakket om XML naar de API te sturen. Echter, deze XSD's hoeven niet gelijk te zijn aan XML welke geretourneerd wordt door de API.
Overzichten:
Alle overzichten op GET methods (Controllers waarbij meerdere 'zelfde' items worden geretourneerd) beschikken over 2 parameters.
- start, int, om aan te geven waar de recordset moet beginnen
- limit, int en hoeveel items geretourneerd moeten worden.
Indien een start, limit combinatie geen 'items' meer bevat dan wordt een HTTP status 404 teruggeven.
http://[mijnapi.url]/v1/[controller]/[id][.xml|.json]?start=2000&limit=1000
Controllers
Controllers, als in MVC: voor de models wordt zoveel als mogelijk gebruik gemaakt van de native code. Zoals die bijv. in Opencart beschikbaar is.
- attributegroupController
- categoryController
- customerController
- customergroupController
- httpTestLog
- indexController
- manufacturerController
- orderController
- productController
- resetController
- dgecustomController
Testplan
In het testplan staan de handelingen beschreven die in dgeDetailhandel/dgeGroothandel uitgevoerd kunnen worden om de communicatie tussen dgeDetailhandel/dgeGroothandel en de OCAPI te testen. Zie Testplan
Updated