5 ms·

Rethinking web API development

58 points by mattetti 14y ago

MatthewPhillips 14y ago
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.
- masklinn 14y ago
  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). That's fine, regular web interactions work and work well and they have structural advantages. They just can't do MVC in any sensible manner.
  - icebraining 14y ago
    Agreed; there's essentially zero correlation between real MVC (as described in papers about the original Smalltalk implementations) and web "MVC frameworks".
cmiles74 14y ago
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.
- mattetti 14y ago
  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.
  - cmiles74 14y ago
    I think I understand what you're saying, the Webmachine documentation is pretty heavy on the REST. That said, in my opinion it could serve any kind of resource, the library itself doesn't force you to build a RESTful interface.
tapajos 14y ago
Matt, now I'm working only with API and I couldn't agree more with you. Last year I worked with a very big and monolithic Rails app and all the time I was wondering about move it for services but it wasn't possible. I'm almost convinced that we can write service layers with a very consistent API and use Rails to consume it as a client. The HTML interface should be only another client.
- MatthewPhillips 14y ago
  Why? HTML is just another output format for a resource. Like Json or Xml.
  - mattetti 14y ago
    @MatthewPhillips maybe because the logic to generate JSON and HTML is very often quite different and having a tight coupling at this level might result in some serious pains later on.
    - MatthewPhillips 14y ago
      How are they tightly coupled? You take the same data and either run it through a Json serializer or a view renderer.
    - mattetti 14y ago
      > You take the same data and either run it through a Json serializer or a view renderer. My experience might be different than yours, but very often my html views quickly end up needed more than 1 resource to render and now I need to fetch data just for the html templates. The same data set isn't needed when returning json or xml and the API end points exposed for data consumption are often quite different. That said, in some cases, I agree that your approach would work.
  - tapajos 14y ago
    @MatthewPhillips, In the real world the HTML output is not like JSON or XML as you told. It is used to show data to a human and most of the time it contains a lot of elements that are not related with the resource data even if it is not representing more than a resource in the same page. The interaction with a human doesn't happen in the same way as with another system.
codenerdz 14y ago
I wonder how would this Weasel_Diesel DSL framework that sort of drives you toward sinatra deal with number one requirement for most APIs --- being secure. In other words, I need it to work well with implementing an oauth provider functionality. Also potentially one needs to come up with a way for an API consumer to be able to generate oauth credentials in a (hopefully) user friendly way. Hence Id prefer full Rails environment with things like Devise and ActiveAdmin
AffableSpatula 14y ago
"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.
- mattetti 14y ago
  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.
  - AffableSpatula 14y ago
    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).
markprovan 14y ago
I'm currently using the rails_api gem for an API only app I'm building. It's pretty lean.
btaitelb 14y ago
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.
jeffpelton 14y ago
I'm working on an open source platform for restful api app development, running on node.js and mongo. The idea is to handle the backend stuff so you can focus on the frontend of your choice. But on open source, so something like wordpress for apps. I'd love input on the idea. https://github.com/comster/house https://github.com/comster/house
jejacks0n 14y ago
Why not build this as a middleware layer? You can mount a sinatra app within Rails (/services for instance), and then write your API in a predefined path structure that the gem will look into (within the rails app path maybe?) You can pretty easily share models and whatnot -- and then you have a nice clean place to define/override your DSL. I would have to do some playing to make sure this is valid, but that might be an approach to think about.
thesuperbigfrog 14y ago
The DSL you describe is remarkably similar to WSDL (http://en.wikipedia.org/wiki/Wsdl http://en.wikipedia.org/wiki/Wsdl) in terms of describing a web service and how to communicate with it. Granted, DSL is a lot easier to read, since it is using Ruby syntax instead of XML. Functionally, they are the same.
throwa 14y ago
Sorry but can someone enlighten me, on why this might be be better than using: https://github.com/josevalim/active_model_serializers https://github.com/josevalim/active_model_serializers, https://github.com/nesquena/rabl https://github.com/nesquena/rabl, https://github.com/rails/jbuilder https://github.com/rails/jbuilder

58 points by mattetti 14y ago

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.

masklinn 14y ago
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). That's fine, regular web interactions work and work well and they have structural advantages. They just can't do MVC in any sensible manner.
- icebraining 14y ago
  Agreed; there's essentially zero correlation between real MVC (as described in papers about the original Smalltalk implementations) and web "MVC frameworks".

cmiles74 14y ago

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.

mattetti 14y ago
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.
- cmiles74 14y ago
  I think I understand what you're saying, the Webmachine documentation is pretty heavy on the REST. That said, in my opinion it could serve any kind of resource, the library itself doesn't force you to build a RESTful interface.

tapajos 14y ago

Matt, now I'm working only with API and I couldn't agree more with you. Last year I worked with a very big and monolithic Rails app and all the time I was wondering about move it for services but it wasn't possible. I'm almost convinced that we can write service layers with a very consistent API and use Rails to consume it as a client. The HTML interface should be only another client.

MatthewPhillips 14y ago
Why? HTML is just another output format for a resource. Like Json or Xml.
- mattetti 14y ago
  @MatthewPhillips maybe because the logic to generate JSON and HTML is very often quite different and having a tight coupling at this level might result in some serious pains later on.
  - MatthewPhillips 14y ago
    How are they tightly coupled? You take the same data and either run it through a Json serializer or a view renderer.
  - mattetti 14y ago
    > You take the same data and either run it through a Json serializer or a view renderer. My experience might be different than yours, but very often my html views quickly end up needed more than 1 resource to render and now I need to fetch data just for the html templates. The same data set isn't needed when returning json or xml and the API end points exposed for data consumption are often quite different. That said, in some cases, I agree that your approach would work.
- tapajos 14y ago
  @MatthewPhillips, In the real world the HTML output is not like JSON or XML as you told. It is used to show data to a human and most of the time it contains a lot of elements that are not related with the resource data even if it is not representing more than a resource in the same page. The interaction with a human doesn't happen in the same way as with another system.

codenerdz 14y ago

I wonder how would this Weasel_Diesel DSL framework that sort of drives you toward sinatra deal with number one requirement for most APIs --- being secure. In other words, I need it to work well with implementing an oauth provider functionality. Also potentially one needs to come up with a way for an API consumer to be able to generate oauth credentials in a (hopefully) user friendly way. Hence Id prefer full Rails environment with things like Devise and ActiveAdmin

AffableSpatula 14y ago

"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.

mattetti 14y ago
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.
- AffableSpatula 14y ago
  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).

markprovan 14y ago

I'm currently using the rails_api gem for an API only app I'm building. It's pretty lean.

btaitelb 14y ago

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.

jeffpelton 14y ago

I'm working on an open source platform for restful api app development, running on node.js and mongo. The idea is to handle the backend stuff so you can focus on the frontend of your choice. But on open source, so something like wordpress for apps. I'd love input on the idea. https://github.com/comster/house https://github.com/comster/house

jejacks0n 14y ago

Why not build this as a middleware layer? You can mount a sinatra app within Rails (/services for instance), and then write your API in a predefined path structure that the gem will look into (within the rails app path maybe?) You can pretty easily share models and whatnot -- and then you have a nice clean place to define/override your DSL. I would have to do some playing to make sure this is valid, but that might be an approach to think about.

thesuperbigfrog 14y ago

The DSL you describe is remarkably similar to WSDL (http://en.wikipedia.org/wiki/Wsdl http://en.wikipedia.org/wiki/Wsdl) in terms of describing a web service and how to communicate with it. Granted, DSL is a lot easier to read, since it is using Ruby syntax instead of XML. Functionally, they are the same.

throwa 14y ago

Sorry but can someone enlighten me, on why this might be be better than using: https://github.com/josevalim/active_model_serializers https://github.com/josevalim/active_model_serializers, https://github.com/nesquena/rabl https://github.com/nesquena/rabl, https://github.com/rails/jbuilder https://github.com/rails/jbuilder