Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Rethinking web API development

matt.aimonetti.net

Post reply on HN
Print view View original

11–20 of 27 posts

Re: Rethinking web API development

#11

Post by mattetti »

cmiles74 wrote: post #6

Why the crack about Webmachine? It seems sensible that you'd want to factor out all of the logic common to every web service so that you wouldn't keep re-writing it for every service you develop. I don't believe that Webmachine forces you into "a specific way of providing your data." It wants you to provide data in a format that both your service and the client are prepared to understand, again, that seams reasonable…

My issue with webmachine is the fact that it forces you into HTTP/REST which might not be a bad thing, but I don't like the lack of flexibility and being stuck in a rigid mold. Besides that, webmachine is great.

Re: Rethinking web API development

#12

Post by AffableSpatula »

"I also didn’t mention the whole REST/RPC/Hypstermedia debate since I consider it being an implementation detail and a totally orthogonal discussion."

with respect to the author this article is well intentioned but it is (in my opinion) fundamentally misguided..

The choice of any of those styles will directly and deeply effect how your clients consume (i.e. couple) to your API.. and ultimately how you are able to evolve and maintain your application over time without heavily disrupting code written against your service.

Rails is perfectly adequate for exposing resources, rendering representations, and for publishing documentation - producing yet another framework that is entirely focused on API might help but in largely superficial ways. The challenge of good API design is in exposing it to the world so that it evokes the right behaviour from an ecosystem of clients you don't control the code for. The details of how you put the API and documentation together in the backend are inconsequential to this challenge since it is all hidden from clients behind HTTP.

Re: Rethinking web API development

#13

Post by mattetti »

AffableSpatula wrote: post #12

"I also didn’t mention the whole REST/RPC/Hypstermedia debate since I consider it being an implementation detail and a totally orthogonal discussion." with respect to the author this article is well intentioned but it is (in my opinion) fundamentally misguided.. The choice of any of those styles will directly and deeply effect how your clients consume (i.e. couple) to your API.. and ultimately how you are able to evo…

I see your point, what I was trying to convey though, was that whatever style you decide to adopt, you still need to value communication, consistency, reliability and maintainability. > "The details of how you put that together in the backend are inconsequential to this challenge since they are hidden behind HTTP." That's is true, except that to integrate well with the "ecosystem of clients you don't control", you need a way to communicate with the people behind the clients. And that's what matters to me whatever technical solution you use.

Re: Rethinking web API development

#15

Post by AffableSpatula »

mattetti wrote: post #13
AffableSpatula wrote: post #12

"I also didn’t mention the whole REST/RPC/Hypstermedia debate since I consider it being an implementation detail and a totally orthogonal discussion." with respect to the author this article is well intentioned but it is (in my opinion) fundamentally misguided.. The choice of any of those styles will directly and deeply effect how your clients consume (i.e. couple) to your API.. and ultimately how you are able to evo…

I see your point, what I was trying to convey though, was that whatever style you decide to adopt, you still need to value communication, consistency, reliability and maintainability. > "The details of how you put that together in the backend are inconsequential to this challenge since they are hidden behind HTTP." That's is true, except that to integrate well with the "ecosystem of clients you don't control", you ne…

the interface you establish is the ultimate form of communication with the people behind the clients. You can't force people to read/obey documentation (no matter how pretty or up-to-date it is), but they are obliged (naturally) to follow the rules of your interface.

It's also worth bearing in mind that the design you pick will directly affect how you document your API - documentation of RPC APIs are different from that of Rails-style CRUD-over-HTTP APIs, which in turn are different from that of REST APIs (or "hypermedia APIs" - redundant term, really).

Re: Rethinking web API development

#16

Post by btaitelb »

Is "Documentation" just an implementation detail for what you really need: "Communication"? If I can have a smooth learning curve and a well-understood contract, then I'll have an API that developers enjoy using and integrating into products. Now granted, I don't see how this can be done currently without proper documentation (even if that just means naming the routes well, and providing illustrative examples), but that doesn't mean it's not possible.

Re: Rethinking web API development

#17

Post by MatthewPhillips »

AffableSpatula wrote: post #15
mattetti wrote: post #13

Earlier quoted context omitted.

I see your point, what I was trying to convey though, was that whatever style you decide to adopt, you still need to value communication, consistency, reliability and maintainability. > "The details of how you put that together in the backend are inconsequential to this challenge since they are hidden behind HTTP." That's is true, except that to integrate well with the "ecosystem of clients you don't control", you ne…

the interface you establish is the ultimate form of communication with the people behind the clients. You can't force people to read/obey documentation (no matter how pretty or up-to-date it is), but they are obliged (naturally) to follow the rules of your interface. It's also worth bearing in mind that the design you pick will directly affect how you document your API - documentation of RPC APIs are different from t…

Also, if you follow REST closely your APIs should be self documenting.

Re: Rethinking web API development

#18

Post by icebraining »

masklinn wrote: post #9
MatthewPhillips wrote: post #5

Is MVC really equipped for this new world? When you write a single page app there's really no need for the V server side, so you left with "MC" and its heavy handed conventions or a Sinatra-like method that more directly maps to RESTful resources.

MVC never worked for regular web pages, it needs bindings and direct feedback to make sense, all the purported MVC web framework were basically full of shit. To "do MVC" on the web, you either do it all on the client, or you split the C across server and clients, with M on the server and V on the client. Something like that. Or you use different meta-patterns, and you stop lying to yourself (and to everybody else). T…

Agreed; there's essentially zero correlation between real MVC (as described in papers about the original Smalltalk implementations) and web "MVC frameworks".

Re: Rethinking web API development

#19

Post by mattetti »

MatthewPhillips wrote: post #17
AffableSpatula wrote: post #15

Earlier quoted context omitted.

the interface you establish is the ultimate form of communication with the people behind the clients. You can't force people to read/obey documentation (no matter how pretty or up-to-date it is), but they are obliged (naturally) to follow the rules of your interface. It's also worth bearing in mind that the design you pick will directly affect how you document your API - documentation of RPC APIs are different from t…

Also, if you follow REST closely your APIs should be self documenting.

I have yet to see a REST interface that self describes in details its incoming params and output. REST gives you discoverability which is different from documentation.

Re: Rethinking web API development

#20

Post by mattetti »

AffableSpatula wrote: post #15
mattetti wrote: post #13

Earlier quoted context omitted.

I see your point, what I was trying to convey though, was that whatever style you decide to adopt, you still need to value communication, consistency, reliability and maintainability. > "The details of how you put that together in the backend are inconsequential to this challenge since they are hidden behind HTTP." That's is true, except that to integrate well with the "ecosystem of clients you don't control", you ne…

the interface you establish is the ultimate form of communication with the people behind the clients. You can't force people to read/obey documentation (no matter how pretty or up-to-date it is), but they are obliged (naturally) to follow the rules of your interface. It's also worth bearing in mind that the design you pick will directly affect how you document your API - documentation of RPC APIs are different from t…

I fully agree, the point that I'm trying to make is that there is a step in between you offering an API and people using it. Explicitly defining your interface will make the transition easier for 3rd party developers.
Post reply on HN