1. Jorrit Duin Avatar Jorrit Duin
  2. generic
  3. OCAPI

Wiki

Clone wiki

OCAPI / nl_index

View History

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]
Beide methoden dienen geïmplementeerd te worden omdat wellicht in de toekomst het dge pakket geschikt wordt om standaard HTTP te kunnen gebruiken.

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
Voor PHP en NODEJS/IO.JS is code aanwezig welke de controle en caching van auth tokens controleert. 
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>
message geeft aan dat een geposte waarden niet goed is, description geeft aan in welk veld de fout geconstateerd is.

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.

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