5 ms·

A number of these points are not really a criticism of RESTful principles per se, but rather of typical REST over HTTP approaches. 1) Asynchronous APIs There'

by pcl 13y ago

A number of these points are not really a criticism of RESTful principles per se, but rather of typical REST over HTTP approaches. 1) Asynchronous APIs There's nothing about REST that says that operations must be performed synchronously. If a client updates a resource via a PATCH method and other services are notified of the update via a web hook or a message bus (possibly including the PATCH or the full resource), the system is still following a RESTful design. 2) Orchestration / Experience APIs A RESTful API does not need to require a separate GET for every individual resource. There's nothing wrong with implementing bulk queries that return variable projections of the server state tuned to the need of particular use cases. Bulk modifications are trickier, especially when atomicity comes into play. But if atomicity is not a concern, then this is more of a transport problem, not a semantic one. 4) Binary protocols Plenty of RESTful APIs (e.g., Twitter[1]) provide data in a number of payload formats. Choice of wire format is unrelated to whether or not the semantics of the API are RESTful. [1] https://dev.twitter.com/docs/things-every-developer-should-know https://dev.twitter.com/docs/things-every-developer-should-k...

nmcfarl 13y ago
I'm fairly certain that when they describe an #2) Orchestration / Experience APIs they mean queries that return heterogeneous data, that one endpoint could retrieve the results of doing many queries, with many data types ie: GET /dashboard.json, retrieving all the resources used to assemble your dashboard page. This is very much different than the normal REST philosophy of returning only homogeneous results. Much more RPC-ish.
- pcl 13y ago
  the normal REST philosophy of returning only homogeneous results Is that a thing? If 'GET /dashboard.json' obeyed the caching semantics of the resources it pulled together to present, and didn't have any surprising side effects, I'd still call that RESTful, even if it returned a rich graph of interesting data.
  - nmcfarl 13y ago
    Yeah - but what if it returned a collection of orders also retrievable from /orders/search?date=today and customers from /customers/search?lastorderdate=today&totallifteimevalue=greaterthan,100000 and support tickets from /support/tickets/search?state=open This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports.
    - sjtgraham 13y ago
      > This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports. This is nothing to do with REST. Read the Wikipedia article for a crash course.
      - nmcfarl 13y ago
        I have, I agree. However the common design patterns for REST APIs encourage canonical URIs for resources, and discourage the same resource being retrieved from multiple locations - which heterogenous collections inevitably lead to. Perhaps I should have said discouraged in the common patterns for implementing REST and REST-like APIs.
        mahmoudimus 13y ago
        I wholeheartedly disagree with you -- you're ignoring hypermedia, an essential component in proper REST architecture. If one correctly leverages hypermedia, you may and most likely will have heterogenous responses and relations. Side-loading relevant relations is highly encouraged and is a core component of efficient API design. To your credit, I believe most of the information out there about REST and REST-like APIs discount how much work actually goes into building a proper REST API with hypermedia -- so we will always have half-baked design patterns that solve problems when doing REST incorrectly.
        gbog 13y ago
X4 13y ago
You probably never heard about these, but these are the best for Binary protocols. If you know something else, or better please post. BEEP: http://www.aspl.es/vortex/ http://www.aspl.es/vortex/ BSON: http://bsonspec.org/ http://bsonspec.org/ (Binary Json)
- ksrm 13y ago
  CBOR [0] is a proposed standard that seems much more efficient than BSON - check out the appendix [1]. [0] http://tools.ietf.org/html/rfc7049 http://tools.ietf.org/html/rfc7049 [1] http://tools.ietf.org/html/rfc7049#appendix-E.6 http://tools.ietf.org/html/rfc7049#appendix-E.6
  - X4 13y ago
    checking out the rfc. cool, thanks!
- tseabrooks 13y ago
  Ah BEEP. I had a grad school project to create a domain specific modeling language that allowed you to diagram the steps for communication and between to systems using BEEP. You'd define the order of messages and the content of the messages the DSML would generate C code that implemented an API to do the communication you'd modeled. God how I hated grad school.
  - X4 13y ago
    That sounds like an amazing experience you had. I can feel the pain! Had to write a custom compiler and backend and vm for it in school. And none of us had experience in C or Assembler. The compiler created a custom bytecode assembly that the VM had to run. Then another group made an FGPA and CPU that runs the code natively. Our prof's hobby was to write an OS for that board. But somehow we managed to do it. I still wow, when I look at the code. It makes me think.. how did I write that?
- dustingetz 13y ago
  http://thrift.apache.org/ http://thrift.apache.org/
bmelton 13y ago
Regarding 2) that's a 'potAYto potAHto' scenario, I think. The way I've used them in the past are to address performance concerns from customers. We have the general RESTful webservices that cover all uses cases, in that every object has an endpoint, blah blah, and the design generally conforms to RESTful paradigms. Beyond that though, customers often request changes, additions, optimizations, etc., and as they're paying us money, we try to be as accommodating as possible. In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience. To use the Github API for reference, to get the status of an issue, you have to query the issues for the repository, then the comments and events for the issue, and then the commit messages that are associated with the events. An example of a non-RESTful paradigm is to simply JOIN the issue's comments and events and associate the relevant commit messages to the events so that they can all be captured in one call. It isn't truly RESTful, but it's awfully damn convenient pertaining to customer overhead, and we still call it REST, and they don't bother correcting us.
- grncdr 13y ago
  An alternative approach that I've implemented in the past [0] (and found quite useful) is client-driven server-side inlining of linked resources. What this means in practice is that the client specifies (usually with a query parameter) what related resources they are interested in, and the server can pre-fetch those resources and include them in the response. Obviously there's some upfront development costs and your API needs to have a well-linked taxonomy of resources, but it allows the client to create these 'flattened views' on the fly with no further work on your part. Edit: Just wanted to clarify that IMO this is a RESTful design because you are still using links to navigate your API resources, you're just writing a "smarter" server that can reduce the number of requests. [0] https://github.com/BetSmartMedia/lazorse-nesting https://github.com/BetSmartMedia/lazorse-nesting edit: fixed link
- sjtgraham 13y ago
  > In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience. This doesn't violate REST. The WWW is the canonical RESTful system, i.e. A client enters the API (a website) via a common entry point (example.com), navigates using links, and manipulates state using a shared understanding of a common media type (HTML and HTML forms). Think about it, when you go to a web page do you expect it to be about strictly one thing, e.g. when viewing a blog post, do you expect it to click a link to navigate to each comment? No, that would be insane. Does that make it non-RESTful? No. It is perfectly reasonable for a resource to be composed of other addressable resources.

by pcl 13y ago

nmcfarl 13y ago

I'm fairly certain that when they describe an #2) Orchestration / Experience APIs they mean queries that return heterogeneous data, that one endpoint could retrieve the results of doing many queries, with many data types ie: GET /dashboard.json, retrieving all the resources used to assemble your dashboard page. This is very much different than the normal REST philosophy of returning only homogeneous results. Much more RPC-ish.

pcl 13y ago
the normal REST philosophy of returning only homogeneous results Is that a thing? If 'GET /dashboard.json' obeyed the caching semantics of the resources it pulled together to present, and didn't have any surprising side effects, I'd still call that RESTful, even if it returned a rich graph of interesting data.
- nmcfarl 13y ago
  Yeah - but what if it returned a collection of orders also retrievable from /orders/search?date=today and customers from /customers/search?lastorderdate=today&totallifteimevalue=greaterthan,100000 and support tickets from /support/tickets/search?state=open This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports.
  - sjtgraham 13y ago
    > This kind of heterogeneous data tends to be very much discouraged under REST, but often very handy in producing real world reports. This is nothing to do with REST. Read the Wikipedia article for a crash course.
    - nmcfarl 13y ago
      I have, I agree. However the common design patterns for REST APIs encourage canonical URIs for resources, and discourage the same resource being retrieved from multiple locations - which heterogenous collections inevitably lead to. Perhaps I should have said discouraged in the common patterns for implementing REST and REST-like APIs.
      - mahmoudimus 13y ago
        I wholeheartedly disagree with you -- you're ignoring hypermedia, an essential component in proper REST architecture. If one correctly leverages hypermedia, you may and most likely will have heterogenous responses and relations. Side-loading relevant relations is highly encouraged and is a core component of efficient API design. To your credit, I believe most of the information out there about REST and REST-like APIs discount how much work actually goes into building a proper REST API with hypermedia -- so we will always have half-baked design patterns that solve problems when doing REST incorrectly.
        gbog 13y ago

X4 13y ago

You probably never heard about these, but these are the best for Binary protocols. If you know something else, or better please post. BEEP: http://www.aspl.es/vortex/ http://www.aspl.es/vortex/ BSON: http://bsonspec.org/ http://bsonspec.org/ (Binary Json)

ksrm 13y ago
CBOR [0] is a proposed standard that seems much more efficient than BSON - check out the appendix [1]. [0] http://tools.ietf.org/html/rfc7049 http://tools.ietf.org/html/rfc7049 [1] http://tools.ietf.org/html/rfc7049#appendix-E.6 http://tools.ietf.org/html/rfc7049#appendix-E.6
- X4 13y ago
  checking out the rfc. cool, thanks!
tseabrooks 13y ago
Ah BEEP. I had a grad school project to create a domain specific modeling language that allowed you to diagram the steps for communication and between to systems using BEEP. You'd define the order of messages and the content of the messages the DSML would generate C code that implemented an API to do the communication you'd modeled. God how I hated grad school.
- X4 13y ago
  That sounds like an amazing experience you had. I can feel the pain! Had to write a custom compiler and backend and vm for it in school. And none of us had experience in C or Assembler. The compiler created a custom bytecode assembly that the VM had to run. Then another group made an FGPA and CPU that runs the code natively. Our prof's hobby was to write an OS for that board. But somehow we managed to do it. I still wow, when I look at the code. It makes me think.. how did I write that?
dustingetz 13y ago
http://thrift.apache.org/ http://thrift.apache.org/

bmelton 13y ago

Regarding 2) that's a 'potAYto potAHto' scenario, I think. The way I've used them in the past are to address performance concerns from customers. We have the general RESTful webservices that cover all uses cases, in that every object has an endpoint, blah blah, and the design generally conforms to RESTful paradigms. Beyond that though, customers often request changes, additions, optimizations, etc., and as they're paying us money, we try to be as accommodating as possible. In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience. To use the Github API for reference, to get the status of an issue, you have to query the issues for the repository, then the comments and events for the issue, and then the commit messages that are associated with the events. An example of a non-RESTful paradigm is to simply JOIN the issue's comments and events and associate the relevant commit messages to the events so that they can all be captured in one call. It isn't truly RESTful, but it's awfully damn convenient pertaining to customer overhead, and we still call it REST, and they don't bother correcting us.

grncdr 13y ago
An alternative approach that I've implemented in the past [0] (and found quite useful) is client-driven server-side inlining of linked resources. What this means in practice is that the client specifies (usually with a query parameter) what related resources they are interested in, and the server can pre-fetch those resources and include them in the response. Obviously there's some upfront development costs and your API needs to have a well-linked taxonomy of resources, but it allows the client to create these 'flattened views' on the fly with no further work on your part. Edit: Just wanted to clarify that IMO this is a RESTful design because you are still using links to navigate your API resources, you're just writing a "smarter" server that can reduce the number of requests. [0] https://github.com/BetSmartMedia/lazorse-nesting https://github.com/BetSmartMedia/lazorse-nesting edit: fixed link
sjtgraham 13y ago
> In many cases, these endpoints are customer-specific, and violate the living daylights out of the RESTful design paradigm -- often exposing 'flattened' views for convenience. This doesn't violate REST. The WWW is the canonical RESTful system, i.e. A client enters the API (a website) via a common entry point (example.com), navigates using links, and manipulates state using a shared understanding of a common media type (HTML and HTML forms). Think about it, when you go to a web page do you expect it to be about strictly one thing, e.g. when viewing a blog post, do you expect it to click a link to navigate to each comment? No, that would be insane. Does that make it non-RESTful? No. It is perfectly reasonable for a resource to be composed of other addressable resources.