Pragmatic REST Webcast: How do you translate methods to be more data-oriented?

Not applicable

I'm Matt, and I am a software engineer at a marketing/lead generation company for higher education. I found the webcast on data-oriented APIs fascinating and am really compelled to start building data-oriented APIs. I'm even thinking about building an open-source framework for data-oriented APIs in Node.js.

My question is: what do we do with methods that just don't directly transcribe to your traditional CRUD operations? For example, I understand the idea of passing some kind of session token with a request in the headers for calls that require a layer of authentication -- but what does the API call that gets this token look like?

In my traditional, operation-driven model, I see an API call that looks like POST /users/logIn {"username":"jdoe","password":"123"}, but that isn't a self-describing API call -- now I need proprietary documentation on the route, the parameters, response codes/messages, etc., making it non-standard. Is there a way to model such a method with a more data-driven approach? It seems to break the purity of these data-oriented approaches, but I can't think of a way to set up more specialized methods without describing arbitrary endpoints.

Examples include:

  • a service that receives user credentials and responds with an error or a token
  • a service that emails a user with a special token for resetting his/her password
  • a service that receives a token and resets a user's password
  • a service that refunds a purchase (but doesn't delete an Order record, of course!)
  • a service that expires the user's token (log out)

I realize that you guys probably get a ton of questions from the conferences, but I just happened to find this one very compelling and would like to model my own work after it. I'll definitely be following your future webcasts! Thanks for this insight!

(I tried emailing the webcast email address shown in the presentation but it bounced back.)

UPDATE:

After thinking about this situation for a bit, I had some thoughts about how to approach these examples while keeping to a data model:

  • a service that receives user credentials and responds with an error or a token
  • Data-driven: a POST endpoint that receives a username and password to, in essence, "create" a token. Other requests, like GET or PATCH, to the /auth-tokens/ endpoint or /auth-tokens/[tokenId] endpoint would be forbidden. The POST call would return a bad request without a proper username/password. In order to describe the data model properly, this still requires documentation on what to pass to the API, and probably should omit the password from the response (for brevity, maybe it is still returned but with a null value). Problem is, the "self" URL won't be accessible.
  • a service that emails a user with a special token for resetting his/her password
  • Data-driven: Similar to the first example. A POST request with the required data "creates" a reset-token resource and returns it.
  • a service that receives a token and resets a user's password
  • Data-driven: Perhaps this is a DELETE request on the reset-token resource.
  • a service that refunds a purchase (but doesn't delete an Order record, of course!)
  • Data-driven: Not sure about this one yet. Maybe a PATCH request on the order resource that sets the order amount to zero and a side-effect is that, server-side, the old order is maintained but its amount credited. Not sure with this one.
  • a service that expires the user's token (log out)
  • Data-driven: Like the previous reset example, this may be a DELETE request with the session token ID.

Matt

3 5 1,823
5 REPLIES 5

@Matt Miller , Welcome to Apigee Community 🙂

Not applicable

@Matt Miller Thanks for your POST, Matt. These are interesting problems and the general direction you are taking makes sense to us. Marsh and I wrote a blog post with some of our own thoughts on solutions. See what you think: http://apigee.com/about/blog/developer/data-oriented-designs-common-api-problems

Thank you so much! The refund thing was obvious, I don't know why I didn't think of Refund as a different resource entirely, but of course it would be. Your examples really clarified the questions I had, and I really didn't expect you to go all out and write a blog post about it! Very much appreciated, and this helps me model my understanding of "operational" calls closer to their resource representations.

Glad you enjoyed it! And thanks for suggesting a solid blog topic. 🙂

the blog post isnt reachable. is this available elsewhere?