Opzet van webapplicatie die zijn eigen public API lust

[Rickets]

Ik mag binnenkort bij een webapplicatie een publieke API met webservices maken. Ik wil dat de webapplicatie zelf gebruik gaat maken van deze webservices, zodat de API als gevolg daarvan lekker omvangrijk wordt. Verder moet het geheel zoveel mogelijk volgens de principes van REST opgezet worden. Eén URL per resource en via HTTP geef je aan wat je er mee wil en in welk formaat. Dit betekent dat zowel webbrowsers die de site bezoeken als programma’s die geschreven zijn met de API, gebruik maken van dezelfde URL’s.

Ik heb meteen maar een schema gemaakt van de opzet die ik in gedachten heb.



Opmerkingen bij het schema:

• De webservices worden gebouwd met OpenRasta. Daarmee kan je snel en simpel REST-spul bouwen en XML, JSON of wat dan ook teruggeven.
• De website mag net wat meer dan de gebruikers van de publieke API, vandaar de splitsing in een deel openbaar en een deel niet-openbaar

Voorbeelden van gebruik:

• Een webbrowser doet een request naar een URL en wil HTML zien. De server herkent dit en laat het request afhandelen door ASP.NET MVC. Die roept vervolgens de webservice aan (openbaar of niet-openbaar, afhankelijk van het request) en krijgt van die webservice een pakketje JSON of XML, waar MVC dan weer HTML van maakt.
• Een extern programma doet een request naar een URL en wil JSON zien. De server herkent dit en laat het request meteen afhandelen door het publieke deel van de webservice, die vervolgens JSON teruggeeft.

Mijn bedenkingen en vragen bij deze opzet:

• Hoe laat ik de server requests de ene keer doorsturen naar MVC en de andere keer meteen naar de webservices? In de voorbeelden heb ik het omschreven als “de server herkent dit” maar ik zou zo niet weten welk stuk software dit zou moeten regelen. Hieruit volgt eigenlijk mijn volgende vraag.
• Is ASP.NET MVC wel nodig? OpenRasta kan overweg met HTML en ASP.NET Views. Validatie zit in de businesslaag, dus daar heb ik MVC niet voor nodig. Een object binden bij een POST kan OpenRasta ook. Dus waarom niet versimpelen: ASP.NET MVC ertussenuit halen en HTML-requests ook door de webservice af laten handelen.
• Als ik de principes van REST volg, blijven acties als “new” en “edit” uit de URL. Welke URL heeft dan bijvoorbeeld het formulier om een nieuwe resource te maken? Stel, ik heb een lijst met bedrijven op http://domain/companies. Ik heb een HTML-formulier waarmee een nieuw bedrijf toegevoegd kan worden. Via welke URL is dit formulier bereikbaar? http://domain/companies/new is volgens REST niet geldig, maar welke dan wel?

Wie heeft al met een of meer van deze vragen geworsteld? Of: wie heeft zin om mee te denken?

[Styxxy]

Ik heb zelf nog niet veel ervaring met deze opzet. Ik heb al een introductie cursus (dat over Apache producten ging) gehad over Service oriented architecture (SOA, niet te verwarren met de ziektes). Ik denk dat als je je daar verder in verdiept, dat je mogelijk enkele antwoorden vindt op jouw vragen.

[ Voor 4% gewijzigd door Styxxy op 05-02-2011 17:44 ]

[djc]

Rickets schreef op zaterdag 05 februari 2011 @ 17:25:

• Hoe laat ik de server requests de ene keer doorsturen naar MVC en de andere keer meteen naar de webservices? In de voorbeelden heb ik het omschreven als “de server herkent dit” maar ik zou zo niet weten welk stuk software dit zou moeten regelen. Hieruit volgt eigenlijk mijn volgende vraag.

Ik ben niet zo bekend met de MS-stack, maar volgens mij kun je het best de MVC-kant en de REST-kant op aparte URLs onderbrengen, zodat zowel client en server makkelijk onderscheid kunnen maken. Ik neem aan dat je verschillende applicaties op de verschillende URL's kan aanspreken.

Rickets schreef op zaterdag 05 februari 2011 @ 17:25:

• Is ASP.NET MVC wel nodig? OpenRasta kan overweg met HTML en ASP.NET Views. Validatie zit in de businesslaag, dus daar heb ik MVC niet voor nodig. Een object binden bij een POST kan OpenRasta ook. Dus waarom niet versimpelen: ASP.NET MVC ertussenuit halen en HTML-requests ook door de webservice af laten handelen.

Lijkt me niet onlogisch, maar ik weet niet zo goed wat MVC en OpenRasta allemaal doen of kunnen.

Rickets schreef op zaterdag 05 februari 2011 @ 17:25:

• Als ik de principes van REST volg, blijven acties als “new” en “edit” uit de URL. Welke URL heeft dan bijvoorbeeld het formulier om een nieuwe resource te maken? Stel, ik heb een lijst met bedrijven op http://domain/companies. Ik heb een HTML-formulier waarmee een nieuw bedrijf toegevoegd kan worden. Via welke URL is dit formulier bereikbaar? http://domain/companies/new is volgens REST niet geldig, maar welke dan wel?

Als je echt goed REST wil doen gebruik je hiervoor de andere HTTP verbs, met name POST (voor create) en PUT (voor edit). Voor bonuspunten maak je je REST API ook grondig HATEOAS; dit komt er op neer dat alle URLs in je API kunnen worden afgeleid van de basis-resource, doordat die aangeeft waar andere resources gevonden kunnen worden (mbv URL templates, zoals gestandaardiseerd bij het IETF).

[Rickets]

djc schreef op zaterdag 05 februari 2011 20:18:
Ik ben niet zo bekend met de MS-stack, maar volgens mij kun je het best de MVC-kant en de REST-kant op aparte URLs onderbrengen, zodat zowel client en server makkelijk onderscheid kunnen maken. Ik neem aan dat je verschillende applicaties op de verschillende URL's kan aanspreken.

Het is mogelijk om verschillende URL's te hebben zoals jij beschrijft, bijvoorbeeld domain.com en api.domain.com. Maar dan heb je een situatie waarin dezelfde resource twee URL's heeft, wat dan weer niet klopt volgens REST. Ik zie het als 1 applicatie. Als je op domain.com iets met text/html opvraagt, krijg je de website. Vraag je dezelfde URL op met application/json, krijg je dezelfde data in JSON-vorm.

djc schreef op zaterdag 05 februari 2011 20:18:
Als je echt goed REST wil doen gebruik je hiervoor de andere HTTP verbs, met name POST (voor create) en PUT (voor edit).

Het is inderdaad de bedoeling om de andere HTTP verbs ook te gebruiken. (Dat staat ook in het begin van mijn verhaal, maar misschien niet zo duidelijk ) Ik snap dat het formulier POST naar /companies om een create te doen, maar ik weet niet wat de URL moet zijn om het formulier te laten zien (een GET) als ik constructies als /companies/new wil vermijden. (Ik hoop dat ik goed uitleg wat ik bedoel.)

djc schreef op zaterdag 05 februari 2011 20:18:
Voor bonuspunten maak je je REST API ook grondig HATEOAS; dit komt er op neer dat alle URLs in je API kunnen worden afgeleid van de basis-resource, doordat die aangeeft waar andere resources gevonden kunnen worden (mbv URL templates, zoals gestandaardiseerd bij het IETF).

Als ik tijd overheb, zal ik dat erbij doen. Voor de bonuspunten.

[mOrPhie]

Wist je dat MVC ook Json terug kan geven op een URL? Je gebruikt dan ipv ActionResult, JsonResult. Zie http://msdn.microsoft.com...m.web.mvc.jsonresult.aspx. Wellicht iets om te onderzoeken.

Of dat zo handig is weet ik verder niet, omdat je dan zelf de verantwoordelijkheid hebt over standaardisatie van je json api. Wellicht dat OpenRasta dat kan opvullen, maar ik heb daar geen ervaring mee. Daarnaast weet ik niet zeker of je op 1 URL zowel een ActionResult als een JsonResult zou kunnen teruggeven. Het zou, C#-technisch moeten kunnen. Ik weet alleen niet of de URL-router van MVC ermee overweg kan.

Hoe dan ook, wellicht iets om mee te nemen in je onderzoek.

[Compuhair]

Rickets schreef op zaterdag 05 februari 2011 @ 17:25:
• Als ik de principes van REST volg, blijven acties als “new” en “edit” uit de URL. Welke URL heeft dan bijvoorbeeld het formulier om een nieuwe resource te maken? Stel, ik heb een lijst met bedrijven op http://domain/companies. Ik heb een HTML-formulier waarmee een nieuw bedrijf toegevoegd kan worden. Via welke URL is dit formulier bereikbaar? http://domain/companies/new is volgens REST niet geldig, maar welke dan wel?
[/list]

Het is wat mij betreft niet nodig om je wep app ook REST urls te geven. REST is zinvol voor een API, maar niet zinvol voor een applicatie.

Je app zou ik daarom url laten houden als 'http://domain/companies/new' en 'http://domain/companies/edit'. En je api krijgt urls als 'http://service.domain/companies'

djc schreef op zaterdag 05 februari 2011 @ 20:18:
Ik ben niet zo bekend met de MS-stack, maar volgens mij kun je het best de MVC-kant en de REST-kant op aparte URLs onderbrengen, zodat zowel client en server makkelijk onderscheid kunnen maken.

Mee eens. Zet je app bijvoorbeeld op www.app.nl en je rest services op serviceX.app.nl, of www.appserviceX.nl o.i.d.

Is ASP.NET MVC wel nodig? OpenRasta kan overweg met HTML en ASP.NET Views. Validatie zit in de businesslaag, dus daar heb ik MVC niet voor nodig. Een object binden bij een POST kan OpenRasta ook. Dus waarom niet versimpelen: ASP.NET MVC ertussenuit halen en HTML-requests ook door de webservice af laten handelen.

(ik kort ASP.NET MVC even af tot MVC)
Ik ken OpenRasta niet, maar de belangrijkste reden om MVC te gebruiken is omdat meer mensen MVC kennen dan OpenRasta (neem ik aan). Dat betekent dat de inwerktijd voor nieuwe devvers op het project korter zal zijn, dat er op internet meer antwoorden zijn op vragen die er spelen etc.
Een reden om alles in OpenRasta te doen zou wat mij betreft zijn als het echt niet gaat in MVC.
Met andere woorden, ik zou over het algemeen kiezen voor de grote lijn in MVC, en specialistische uitzonderingen oplossen met andere tools, zoals OpenRasta.

[Compuhair]

mOrPhie schreef op zondag 06 februari 2011 @ 22:12:
Wist je dat MVC ook Json terug kan geven op een URL? Je gebruikt dan ipv ActionResult, JsonResult. Zie http://msdn.microsoft.com...m.web.mvc.jsonresult.aspx. Wellicht iets om te onderzoeken.

Dat kan heel handig zijn als je even snel een method wil maken die json teruggeeft en bijvoorbeeld door een jquery call gebruikt gaat worden.

Het is minder handig om een hele api op die manier te maken, omdat je minder controle hebt over de configuratie dan je bijvoorbeeld hebt met WCF.

[roy-t]

wat een management vriendelijk hip, gekleurd diagram heb je er bij gemaakt trouwens! Hulde!

[djc]

Compuhair schreef op maandag 07 februari 2011 @ 09:21:
Het is wat mij betreft niet nodig om je wep app ook REST urls te geven. REST is zinvol voor een API, maar niet zinvol voor een applicatie.

Je app zou ik daarom url laten houden als 'http://domain/companies/new' en 'http://domain/companies/edit'. En je api krijgt urls als 'http://service.domain/companies'

Hmm, bepaalde REST-principes gelden niet voor je webapp, maar andere wel. Bijvoorbeeld de idempotency van GET requests is ook zeker aan de applicatie kant heel relevant.

Maar /companies/new lijkt me een prima URL voor het formpje voor een nieuwe company.

Ohja, en als je het netjes wil doen met API/app dingen op dezelfde adressen (iedere resource een enkel adres) moet je de Accept-header goed gebruiken. Laat bijvoorbeeld al je API-calls als Accept application/json meegeven, vervolgens kun je server-side kijken of het een gewone browser is (die een vrij uitgebreide Accept meegeeft) of een API caller.

[mOrPhie]

Wat is trouwens, afgezien van dat het kan en technisch grappig is, de rationale erachter om de app en api functionaliteit achter 1 URL te houden? Ik denk namelijk dat het werkend krijgen van dat concept wellicht meer tijd kost dan het oplevert. Ook in het onderhoud/beheer kan het lastig zijn, omdat je dan naar de HTTP header moet kijken om te bepalen of het een API of App call betrof.

Een eventueel argument zou kunnen zijn om dubbel codewerk te voorkomen, maar dat wijs ik af. De implementatie van functionaliteit kun je prima encapsuleren en vanuit de MVC controller en je API schil die implementatie aanspreken.

[D-Raven]

Naast wat mOrPhie zegt. Hoe ga je vanuit je app die service aanroepen? Als dat REST services zijn welke met OpenRasta geimplementeerd zijn, dan zul je waarschijnlijk (lijkt me niet dat er een wsdl is) zelf webrequests moeten gaan bouwen om de boel aan te roepen. Lijkt me verre van ideaal..

Of ga je in je app de service via ajax aanroepen vanuit je UI ?

[TheNameless]

Inderdaad.
Naast onderhoud/beheer moet ook rekening houden met het feit dat al je data geserialiseerd moet worden tussen de API en je MVC layer. Dat is zonde.

Een dergelijk opzet lijkt me eigenlijk alleen zinvol als je je website volledig in javascript maakt. Dus dat je het daadwerkelijk genereren van je HTML op de client doet.

Lijkt mij logischer als je je MVC blok, zegmaar naast je webservices blokje plaats i.p.v. erboven.

[ Voor 13% gewijzigd door TheNameless op 07-02-2011 11:35 ]

[Rickets]

mOrPhie schreef op zondag 06 februari 2011 22:12:
Wist je dat MVC ook Json terug kan geven op een URL? Je gebruikt dan ipv ActionResult, JsonResult. Zie MSDN: JsonResult Class (System.Web.Mvc). Wellicht iets om te onderzoeken.

Daar ben ik van op de hoogte, maar zoals Compuhair zegt, wordt dat snel rommelig in een uitgebreide webservice, waar iedere URL een of meer bestandstypen moet kunnen teruggeven.

roy-t schreef op maandag 07 februari 2011 09:50:
wat een management vriendelijk hip, gekleurd diagram heb je er bij gemaakt trouwens! Hulde!

offtopic:
Bedankt! Ik mag graag kleuren.

Compuhair schreef op maandag 07 februari 2011 09:21:
Het is wat mij betreft niet nodig om je wep app ook REST urls te geven. REST is zinvol voor een API, maar niet zinvol voor een applicatie.

Je app zou ik daarom url laten houden als 'http://domain/companies/new' en 'http://domain/companies/edit'. En je api krijgt urls als 'http://service.domain/companies'

mOrPhie schreef op maandag 07 februari 2011 10:31:
Wat is trouwens, afgezien van dat het kan en technisch grappig is, de rationale erachter om de app en api functionaliteit achter 1 URL te houden? Ik denk namelijk dat het werkend krijgen van dat concept wellicht meer tijd kost dan het oplevert. Ook in het onderhoud/beheer kan het lastig zijn, omdat je dan naar de HTTP header moet kijken om te bepalen of het een API of App call betrof.

Ik zie de applicatie en API als één geheel. Je hebt URL’s en daarachter zitten gegevens, die op een bepaalde manier weergegeven worden. De gangbaarste manier is natuurlijk HTML, maar dat moet net zo makkelijk wat anders kunnen zijn.
Ik snap dat dat geen recht doet aan de realiteit, maar ik ben slechts op zoek naar een methode die goed werkt en mij bevalt. Voordat ik een hele API bouw, overpeins ik een aantal dingen en probeer ik wat uit. Sommige dingen vallen af, sommige niet. Ik vrees dat één URL voor zowel app als API af gaat vallen.

mOrPhie schreef op maandag 07 februari 2011 10:31:
Een eventueel argument zou kunnen zijn om dubbel codewerk te voorkomen, maar dat wijs ik af. De implementatie van functionaliteit kun je prima encapsuleren en vanuit de MVC controller en je API schil die implementatie aanspreken.

Nee, één URL was slechts een benadering vanuit REST-principes, meer niet.
Zoals je in het schema ziet, wil ik wellicht een stap verder gaan dan wat jij schetst: MVC roept de API aan, die de implementatie aanroept.

Deathraven schreef op maandag 07 februari 2011 11:10:
Naast wat mOrPhie zegt. Hoe ga je vanuit je app die service aanroepen? Als dat REST services zijn welke met OpenRasta geimplementeerd zijn, dan zul je waarschijnlijk (lijkt me niet dat er een wsdl is) zelf webrequests moeten gaan bouwen om de boel aan te roepen. Lijkt me verre van ideaal..

Ja, dat is de bedoeling. Eventueel stop ik de webrequests in een client library, die ik dan open source maak, zodat publieke gebruikers meteen aan de slag kunnen. Waarom lijkt je dat verre van ideaal? Je wordt dan gedwongen om de service zo goed mogelijk te regelen, in plaats van dat het iets is dat je er even naast doet. Kwaliteit ten koste van wat overhead.

[Compuhair]

Rickets schreef op maandag 07 februari 2011 @ 21:59:

Waarom lijkt je dat verre van ideaal?

Belangrijkste reden is denk ik dat het zelf bouwen van de REST requests veel meer tijd kost dan het aanroepen van een 'normale' method, en bovendien veel foutgevoeliger is.

Ik zie een REST api met name toegevoegde waarde hebben in situaties waarin interoperabiliteit zeer belangrijk is. In jouw situatie geldt dit dus mogelijk voor de public webservices. Waar het echter niet voor geldt, blijkens jouw verhaal, is voor het gedeelte 'MVC.Net App < - > Business Logica / Database / etc.'. Omdat beide delen prima in C# gemaakt kunnen worden, is er geen reden om daar een taalonafhankelijk mechanisme tussen te gaan zetten, dat een groot deel van de sterke kanten van C# overboord gooit. Sterker nog, daar haal je je alleen maar meer werk en problemen mee op de hals.

[creator1988]

Rickets schreef op maandag 07 februari 2011 @ 21:59:
Ik zie de applicatie en API als één geheel. Je hebt URL’s en daarachter zitten gegevens, die op een bepaalde manier weergegeven worden. De gangbaarste manier is natuurlijk HTML, maar dat moet net zo makkelijk wat anders kunnen zijn.
Ik snap dat dat geen recht doet aan de realiteit, maar ik ben slechts op zoek naar een methode die goed werkt en mij bevalt. Voordat ik een hele API bouw, overpeins ik een aantal dingen en probeer ik wat uit. Sommige dingen vallen af, sommige niet. Ik vrees dat één URL voor zowel app als API af gaat vallen.

Als ik dit lees, denk ik aan Coding Glamour: Rails' respond_to in ASP.NET MVC

Overigens eten wij onze API ook. Dit is een WCF API die via REST benaderbaar is op een ander domein en ook via WSHTTP. In onze eigen apps maken we een Service Reference aan, en dan genereert Visual Studio de gehele client library. Ook hier hebben we een publieke en een interne versie, de interne versie is gelockt op een aantal API keys en bovendien op IP adres. Je kunt met inheritance in WCF dit eenvoudig realiseren.

[Verwijderd]

Hoe laat ik de server requests de ene keer doorsturen naar MVC en de andere keer meteen naar de webservices? In de voorbeelden heb ik het omschreven als “de server herkent dit” maar ik zou zo niet weten welk stuk software dit zou moeten regelen. Hieruit volgt eigenlijk mijn volgende vraag.

Hoewel ik geen kennis heb van ASP.NET, heb ik wel een REST-API lopen voor een web applicatie, welke is geschreven in PHP. In dit geval het ik de applicatie en de API los van elkaar gehaald om problemen te voorkomen (en omdat de calls niet door beide worden gebruikt). Op deze manier worden alleen de Models gedeeld, terwijl de Controllers en Views gescheiden zijn.

Is ASP.NET MVC wel nodig? OpenRasta kan overweg met HTML en ASP.NET Views. Validatie zit in de businesslaag, dus daar heb ik MVC niet voor nodig. Een object binden bij een POST kan OpenRasta ook. Dus waarom niet versimpelen: ASP.NET MVC ertussenuit halen en HTML-requests ook door de webservice af laten handelen.

Hoewel ik niet weet hoe OpenRasta werkt (of ASP.NET in het algemeen), zou ik me kunnen voorstellen dat je tegen problemen aanloopt zonder MVC, bijvoorbeeld bij calls die niet door de webservice kan worden afgehandeld.

Als ik de principes van REST volg, blijven acties als “new” en “edit” uit de URL. Welke URL heeft dan bijvoorbeeld het formulier om een nieuwe resource te maken? Stel, ik heb een lijst met bedrijven op http://domain/companies. Ik heb een HTML-formulier waarmee een nieuw bedrijf toegevoegd kan worden. Via welke URL is dit formulier bereikbaar? http://domain/companies/new is volgens REST niet geldig, maar welke dan wel?

Hier heb je al een probleem die niet kan worden afgehandeld door REST, omdat deze de acties met HTTP methods word bepaald (GET, POST, PUT, DELETE) ipv de URI. Zie hier de structuur. Het aanroepen van een formulier kan dus niet (volgens REST).

[mOrPhie]

Rickets schreef op maandag 07 februari 2011 @ 21:59:
Voordat ik een hele API bouw, overpeins ik een aantal dingen en probeer ik wat uit. Sommige dingen vallen af, sommige niet. Ik vrees dat één URL voor zowel app als API af gaat vallen.

Alle opties overwegen is een goeie eigenschap hoor, dus daarvoor kudo's. Ik denk dat ik inderdaad tot dezelfde conclusie zou zijn gekomen.

Nee, één URL was slechts een benadering vanuit REST-principes, meer niet.
Zoals je in het schema ziet, wil ik wellicht een stap verder gaan dan wat jij schetst: MVC roept de API aan, die de implementatie aanroept.

Oh ja. Ik zie het.
Waarom zou je dat doen? Even een "-ility' analyse:

Voor scalability kun je ook de hele website dupliceren. Voor maintainability vind ik het lastig, aangezien je nu twee verschillende doelen (een public API en een applicatie) in één API moet verenigen. Je reliability gaat omlaag (je krijgt 2 endpoints en dus 2 momenten waarop het mis kan gaan). Je availability verhoog je er niet mee. Je performance gaat omlaag, al is het wellicht de vraag of dat zo erg is. Wellicht dat managability hoger is, aangezien je alle calls op http-niveau kunt loggen, maar is dat echt nodig?

Ik zit nu vooral in de vragenstel-modus. Dat is niet om je ideeën af te kraken (integendeel!), maar om hardop na te denken of je keuzes en aannames wel kloppen.