[PHP] Opzetten REST API

[Verwijderd]

Beste leden,

Heb al heel wat gegoogle en nog niet heel veel kunnen vinden over het opzetten van een API. Wij willen voor ons systeem een API gaan bouwen waarmee klanten extern producten kunnen toevoegen / wijzigen / deleten en meer. Deze API willen we opbouwen door middel van classes.

Een globale opzet waar we nu aan zitten te denken is als voorbeeld onderstaande url:
http://www.website.nl/com...mmand=EMAIL&parameters...

Iemand doet zoals bovenstaande url aangeeft een API call welke binnenkomt op command.php hier zal worden gevalideerd worden of de apiuser en apipass correct zijn en of hij deze command mag uitvoeren.

Het command kan bestaan uit verschillende acties als:

• ADD
• DEL
• GET
• LIST
• UPD
• UPGR

Een gebruiker die binnenkomt op de command.php en goed gevalideerd is, moet dus doorgestuurd worden naar het desbetreffende command zoals bovenstaande mogelijkheden.

Mijn idee is:
- command.php class (class welke alles in werking gaat zetten)
- command class (voor add, del, get enz)
- subcommand classes (voor de verwerking van het subcommand)

De globale vraag is nu, welke structuur voor classes kunnen we het beste gaan toepassen voor de opzet van deze API.

Piete

[Janoz]

Ik zou aan de andere kant beginnen.Implementeer voor je domein (entiteiten ed) een mooie DAO/TO oplossing. Hieruit volgt zo ongeveer automatisch een interface die keurig op de gekozen commandstructuur past. Je 'command class' hoeft dan eigenlijk alleen maar de juiste dao te pakken en daarin de juiste methode aan te roepen.

[Janoz]

Dit topic past trouwens beter in SEA

[djc]

Het klinkt niet alsof je het echt over een REST-achtige API hebt. Bij een REST-api gebruik je gewoon de HTTP methods om resources te manipuleren (GET om iets uit te lezen, POST om iets nieuws te maken, PUT om iets te wijzigen, DELETE om iets te verwijderen). Als je het echt goed wil doen gebruik je Hyperlinks As The Engine Of Application State. Lees bijvoorbeeld de Atompub RFC voor een goed voorbeeld, of de conversaties met een imaginary eBay architect voor meer uitleg.

Mocht je het hele REST-principe eigenlijk niet zo boeiend vinden, ga dan gewoon voor een vorm van RPC, bijvoorbeeld XML-RPC (en dan heb je meteen allemaal standaard-oplossingen voor dingen als commands).

(En vanuit deze optiek vind ik Janoz' antwoord dus ook niet zo sterk.)

[ Voor 22% gewijzigd door djc op 26-01-2010 21:49 ]

[orf]

Als je naar bestaande oplossingen wilt kijken, dan is Zend Framework ook een goede optie. Daar zit een REST API client en server in. Als je het niet wilt gebruiken dan is de structuur in ieder geval wel iets waar je naar kunt kijken.

[Verwijderd]

Heb wat van de gegeven voorbeelden bekeken, maar zit dan met wat vragen.

XML-RPC: Heb de pagina maar wat ik uit de documentatie begrijp is dat de call naar de server ook een XML opbouw is en niet doormiddel van de url zoals in mijn start topic beschreven. Of is dit niet juist wat ik zeg en kan je de aanvraag ook direct via de browser doen?

Zend Framework: Hier gebruiken ze de REST methode, maar heb idd het idee dat dit niet is wat we zoeken. Ze werken hier idd met de vaste commands GET POST PUT en DELETE. En dan zijn toch nog wat beperkt in de mogelijkheden die we eigenlijk willen.

[Janoz]

djc heeft gelijk. De eigenschap van REST is dat je niet een url gebruikt, maar de acties gedefinieerd in het http protocol. Naast GET, POST, PUT en DELETE heb je ook nog HEAD en dan houdt het op. En probeer het niet in je hoofd te halen om aan 1 van de acties een andere actie toe te kennen, aangezien de betekenis van deze onderdelen vast staat.

Is het niet toereikend, dan is REST niet hetgene waar jullie naar op zoek zijn. Ik ben echter wel benieuwd waarom deze 5 acties niet toereikend zijn.

@djc: Je hebt gelijk. Ik zit niet zo heel sterk in REST, vandaar dat mijn reactie zich vooral richt op het deel vlak na de interface. Of je nu REST, XML-RPC of, zoals de topicstarter, een proprietary url base protocol wil implementeren, allen kunnen redelijk simpel gemapt worden op een DAO/TO oplossing.

[.oisyn]

djc schreef op dinsdag 26 januari 2010 @ 21:47:
(GET om iets uit te lezen, POST om iets nieuws te maken, PUT om iets te wijzigen, DELETE om iets te verwijderen).

Zijn PUT en POST nou niet juist precies andersom? Met PUT plaats je iets nieuws, met POST maak je mutaties aan een resource.

(Overigens is REST meer een concept en is HTTP een implementatie daarvan - het ligt voor de hand dat de TS ook HTTP wilt gebruiken, maar dat hoeft voor een REST implementatie dus niet.)

.edit: ik zie nu dat wikipedia het ook op jouw manier omschrijft. Vaag, ik vind het wat tegenintuitief eigenlijk

[ Voor 35% gewijzigd door .oisyn op 27-01-2010 13:00 ]

[Verwijderd]

Ben me nu aan het inlezen in de REST mogelijkheden ism zend framework. Wat ik nog niet helemaal begrijp kan een gebruiken via de adres balk ook een API call uitvoeren om bijvoorbeeld te testen?

[ Voor 86% gewijzigd door Verwijderd op 27-01-2010 13:48 ]

[HuHu]

Als je iets in de adresbalk van een browser intypt en vervolgens die URL gaat bezoeken, dan is dat altijd een GET.

[Verwijderd]

Ja opzich logisch, maar niet geheel functioneel voor onze situatie.

[mithras]

Maar je hoeft dus niet per se een RESTful applicatie te maken? Je kan net zo goed met xml-rpc aan de slag als ik het zo lees. Kan je een eigen xml format vastleggen in dtd en kan je de api gemakkelijk beheersen

[Verwijderd]

We zijn nu enkel aan het oriënteren we hebben nog geen keuze gemaakt.

[NetForce1]

Als je wilt testen door zelf requests te typen kan dat ook via telnet, dan kun je ook de method opgeven. Maar dan moet je ook wel de hele request zelf maken.

[djc]

Verwijderd schreef op woensdag 27 januari 2010 @ 13:24:
Ben me nu aan het inlezen in de REST mogelijkheden ism zend framework. Wat ik nog niet helemaal begrijp kan een gebruiken via de adres balk ook een API call uitvoeren om bijvoorbeeld te testen?

Als je simpel wil testen kun je vaak wel bijvoorbeeld wget of curl gebruiken om ook de andere methods te testen.

Volgens mij zijn er trouwens nog wel meer semi-gestandaardiseerde methods, bijvoorbeeld PATCH, maar die worden meestal niet gebruikt.

Anyway, wat mij betreft is HATEOAS wel een belangrijk onderdeel van een REST-api, maakt schalen ook relatief makkelijk.

[Soultaker]

Essentieel aan REST is dat je in ieder geval de idempotentie van GET requests respecteert (dus GET requests veranderen de server-side state niet). Mutaties moeten dan sowieso via PUT of POST. Tenslotte is het de bedoeling om objecten aan de server-kant weer te geven als HTTP resources, waarbij je het padcomponent van URLs gebruikt om resources te identificeren.

Je zou bijvoorbeeld de contactinformatie van een persoon kunnen opvragen door een GET request te doen op http://example.com/users/john?format=vcard. Een modificatie doe je dan met POST of PUT.

Verder houdt een "REST API" niet veelmeer in dat requests min of meer direct over HTTP gestudeerd worden, en dus zonder envelop/tussenformaat in de vorm van XML/RPC of SOAP. Het is sowieso een vrij los gedefinieerd concept.

.oisyn schreef op woensdag 27 januari 2010 @ 12:52:
Zijn PUT en POST nou niet juist precies andersom? Met PUT plaats je iets nieuws, met POST maak je mutaties aan een resource.

De manier waarop ik het beschouw is dat je data met PUT conceptueel opslaat in een resource en dus met een GET request weer op kunt vragen. Zo werkt dat ook met bijvoorbeeld WebDav: als ik een (succesvolle) PUT request doe naar een URL met als content "Hello world!", en vervolgens een GET request doe op die URL, verwacht ik diezelfde content terug te krijgen (misschien niet byte-voor-byte, maar toch ongeveer).

Met POST stuur je data naar een resource, waarbij die gegevens op de een of andere manier verwerkt worden. Bekende manieren zijn een webformulier om een e-mail te sturen of een bestelling te plaatsen. Als je zo'n bestelling naar een URL POST, gebeurt er wel iets mee, maar de gegevens als zodanig ben je in principe kwijt. Het is dus meer een black box. Een GET request doen op een form mail script zal niets zinnigs opleveren.

Ik denk dus de meeste applicaties gewoon POST moeten gebruiken (zoals ze nu ook doen) en dat PUT gereserveerd is voor toepassingen waarbij je data in resources opslaat: Subversion, Amazon S3, enzovoorts.

Disclaimer: bovenstaande is meer gebaseerd op mijn ervaring van wat gebruikelijk is, dan op een officiële bron.

[djc]

Soultaker schreef op woensdag 27 januari 2010 @ 15:38:
Essentieel aan REST is dat je in ieder geval de idempotentie van GET requests respecteert (dus GET requests veranderen de server-side state niet). Mutaties moeten dan sowieso via PUT of POST. Tenslotte is het de bedoeling om objecten aan de server-kant weer te geven als HTTP resources, waarbij je het padcomponent van URLs gebruikt om resources te identificeren.

Je zou bijvoorbeeld de contactinformatie van een persoon kunnen opvragen door een GET request te doen op http://example.com/users/john?format=vcard. Een modificatie doe je dan met POST of PUT.

In plaats van een format param in je query string zou het dan wel netter zijn om de Accept header te gebruiken. Of zelfs gewoon een extensie (dus /users/john.vcard).

Soultaker schreef op woensdag 27 januari 2010 @ 15:38:Verder houdt een "REST API" niet veelmeer in dat requests min of meer direct over HTTP gestudeerd worden, en dus zonder envelop/tussenformaat in de vorm van XML/RPC of SOAP. Het is sowieso een vrij los gedefinieerd concept.

Niet helemaal waar. Het is een architecturale stijl, die met een zekere nauwkeurigheid is beschreven in de dissertatie van Roy Fielding.

Soultaker schreef op woensdag 27 januari 2010 @ 15:38:Met POST stuur je data naar een resource, waarbij die gegevens op de een of andere manier verwerkt worden. Bekende manieren zijn een webformulier om een e-mail te sturen of een bestelling te plaatsen. Als je zo'n bestelling naar een URL POST, gebeurt er wel iets mee, maar de gegevens als zodanig ben je in principe kwijt. Het is dus meer een black box. Een GET request doen op een form mail script zal niets zinnigs opleveren.

Dit is wel een goede beschrijving. Volgens mij kom je dit verschil ook duidelijk tegen in Atompub.