API Chaining

[Owen Rubel]

Am putting together conference materials for API abstraction through the front controller with an API Object to do API Chaining in the URL and would love feedback.

Below are some basic videos I put together showing details of each of these principles in a VERY basic manner (without code). Feedback is greatly appreciated.

API Chaining (part 1) : The API Object - http://youtu.be/O4qNQ...­
API Chaining (part 2) : API Chaining - http://youtu.be/O4qNQ...­

A basic implementation can be found in the grails api toolkit.

https://github.com/orubel/grails-api-toolkit

[Owen Rubel]

My apologies... the urls should be

API Chaing (part1) - http://youtu.be/ceg0Y3bDh8k

API Chaining (part 2) - http://youtu.be/O4qNQUhxcRg

[Evan Cordell]

I looked at this a while ago and started to reply, but looks like I lost my draft.

This is a pretty interesting approach, and I like that you're going out of your way to explain it and open source your ideas. (I read through some of the work on github, mainly skimming the docs on API Chaining in particular).

I can see how there are situations where an API Object like you describe could be useful. I question some of the specifics though, it sounds like you're describing  a specific problem and a specific solution rather than a general one. (In your first video you make claims about where things like authorization and validation can happen/must happen and how the API Object makes this better; I'm not sure I agree that your description of the problem applies to web services in general, but presumably it's an accurate description of a system/set of systems you've worked with.)

But all of that is basically a pit stop on the way to the API Chaining idea. My initial reaction to the description you give of API Chaining is that it's not the best solution to the problem, but it's possible I simply don't fully understand the purpose or the problem you're trying to solve.

Some things that concerned me:

 - If you have a chain that ends in an unsafe method ("postchain"), then you're performing unsafe methods through requests you don't expect to be unsafe (i.e. a GET triggers actual changes on the server), and I'm wary of this because it opposes HTTP semantics and could easily cause problems for less-informed clients.

 - I don't understand the reasoning for why the only options for a chain are "postchain" and "prechain". If you're chaining operations already, I don't see why you couldn't chain a group of unsafe operations together as well (I see why you probably shouldn't, but I see no technical limitations in play).

The purpose of chaining, as I understand it, is to reduce the number of API calls needed to perform a specific task. I think I would assert that are at least two other reasonable solutions to this:

   1. Depending on how your responses are structured, you could reduce a "postchain" and "prechain" to simply two requests: one GET and one unsafe method, assuming that you could expand links in requests through parameters. Your chaining example from the video could be GET /persons/1/?expand=purchase or even just GET /persons/1/purchase

   2. As the service provider, you could write the "chain" yourself and expose that as a new endpoint. From your example in the video, instead of chaining GET > GET -> POST as one GET request, you could simply have a POST /purchases/ with content { "personId" = 1 }, and then it's up to you, the service provider, to get the purchase associated with that person and update it appropriately. (Although I would model this specific case as a GET followed by a PUT).

This second approach is the one I tend to take in general with API design: Expose what seems to me to be the most useful/basic endpoints, and then as time goes on and specific use-cases become apparent, add "shortcut" endpoints to address them. For example: if I have a service that lets you post to a forum either anonymously or with a user account, then I might have endpoints for making a post and making an account. If I then see that people using my API use them in conjunction (say, have an option to create an account at the same time as posting your first post), I might make a new endpoint that lets you simultaneously create a post and a user at the same time.

If I've somehow missed the point of this work please correct me. It seems interesting, but from what I can tell, not something that I would personally use (because I like the other solutions I've described better; though they do trade some flexibility for ease of implementation and cachability).

[Owen Rubel]

heh. These are all great questions that I get alot.

First the mixed request (safe and unsafe) is done every day by developers everywhere. It's called a POST form. People send form data va a POST and then send GET data in the URL. This is effectively the exact same thing.

The request encoded is ONLY the unsafe method; the url encoding tells you at what point to read it in. Everything else is just safe methods for returning data... nothing is changed. And since the API Object can have roles and definitions applied at the request/response, all role checking and id checks can be done in the front controller prior to accessing the controller/method and the model.

You can reduce a chain to two requests but you are thinking of this in strictly restful terms still wherein the url is associated with the model/dataset; I'm talking about abstracting the api AWAY from the model. This changes REST is alot of ways in that we not have to consider the API as an abstraction of the returning data wherein we can now apply rules and definitions at the api object in the api layer and NOT at the model.

Once we can abstract the api layer, we can have one common dataset returned from the model that can be returned for separate privileges entirely differently because the api object determines those rules. For example, setting roles/privileges at the api object for the returning dataset allows us to determine if a privilege level of ADMIN gets the entire dataset returned in a response or whether a USER gets a partial return of the dataset in the response. But the model can still validate manage the dataset the same for all it's assets.

And since the api objects are aware of roles/privileges and the relationships between objects, they can relate them selves to one another and give access on the backend even in a user does not have access thus obfuscating keys. A consuming service must still have access but in a chain, the backend can consume what it wants, it just won't expose. So chaining can provide access without exposing keys and without having to index strings either.

There are a ton of applications and benefits to the obfuscation of the api layer. Api chaining is one. ID obfuscation is another. I'm actually coming up with more and more as I keep developing this out... heh.

Owen Rubel
415-971-0976
oru...@gmail.com

--
You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/shHK0LJtqxo/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Owen Rubel]

Oh and yes, as to your second point, you can force people to do multiple requests. However the reason why people are interested in this is that it reduces those multiple requests; if a service can make ONE request rather than 5 and you have 100,000 consuming services, how do you think that will impact your traffic... especially with caching, MQ and other services? You can dramatically decrease your traffic with API Chaining. And since this is VERY easy to automate, you can auto create these chains based on privileges.

I actually have the apidocs in the API Toolkit creating the first level chains and caching them.

Owen Rubel
415-971-0976
oru...@gmail.com

On Sat, Apr 5, 2014 at 11:36 AM, Evan Cordell <cordel...@gmail.com> wrote:

--

[Owen Rubel]

To respond as to why this is SAFE, this uses the same methodology that form POST's use. To refute this would be to refute millions of developers since the 90's saying that sending GET encoded data with a form POST method is unsafe.

As to why we can only send ONE UNSAFE method, how many request methods can you send at once with a single request? That is the answer to your question. Also even if you could send more, you would have a difficulty determining path placement sending a map with the request. This way we send the path map in the url and don't have to determine what the method is; we match method with each request and if we match the UNSAFE method (or an unsafe method is caught) we end the request.