{ Community }
  • Academy
  • Docs
  • Developers
  • Resources
    • Community Articles
    • Apigee on GitHub
    • Code Samples
    • Videos & eBooks
    • Accelerator Methodology
  • Support
  • Ask a Question
  • Spaces
    • Product Announcements
    • General
    • Edge/API Management
    • Developer Portal (Drupal-based)
    • Developer Portal (Integrated)
    • API Design
    • APIM on Istio
    • Extensions
    • Business of APIs
    • Academy/Certification
    • Analytics
    • Events
    • Hybrid
    • Integration (AWS, PCF, Etc.)
    • Microgateway
    • Monetization
    • Private Cloud Deployment
    • Insights
    • IoT Apigee Link
    • BaaS/Usergrid
    • BaaS Transition/Migration
    • Apigee-127
    • New Customers
    • Topics
    • Questions
    • Articles
    • Ideas
    • Leaderboard
    • Badges
  • Log in
  • Sign up

Get answers, ideas, and support from the Apigee Community

  • Home /
  • API Design /
avatar image
3
Question by Matt Miller · Dec 24, 2015 at 08:53 PM · 950 Views api designrestdatawebinar

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

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

Comment
Add comment Show 1
10 |5000 characters needed characters left characters exceeded
▼
  • Viewable by all users
  • Viewable by Apigeeks only
  • Viewable by the original poster
  • Viewable by moderators
  • Viewable by moderators and the original poster
  • Advanced visibility
Viewable by all users
avatar image Anil Sagar @ Google ♦♦   · Jan 04, 2016 at 05:15 AM 1
Link

@Matt Miller , Welcome to Apigee Community :)

Close

1 Answer

  • Sort: 
avatar image
6

Answer by Martin · Jan 06, 2016 at 07:44 PM

@Matt Miller Thanks for your POST, Matt. These are interesting problems and the general direction you are taking makes sense to us. anonymized-user 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

Comment
Add comment Show 2 · Link
10 |5000 characters needed characters left characters exceeded
▼
  • Viewable by all users
  • Viewable by Apigeeks only
  • Viewable by the original poster
  • Viewable by moderators
  • Viewable by moderators and the original poster
  • Advanced visibility
Viewable by all users
avatar image Matt Miller · Jan 07, 2016 at 03:34 PM 0
Link

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.

avatar image marshg@google.com ♦♦ Matt Miller · Jan 08, 2016 at 12:02 AM 0
Link

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

Follow this Question

Answers Answers and Comments

25 People are following this question.

avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image avatar image

Related Questions

Design a rest api with multiple date range 1 Answer

San Jose API Meetup January 27th 0 Answers

API Swagger spec Creation from the xsd file or from the scratch 0 Answers

YAML Payload request to APIGEE 2 Answers

API Productization Best Practices 1 Answer

  • Products
    • Edge - APIs
    • Insights - Big Data
    • Plans
  • Developers
    • Overview
    • Documentation
  • Resources
    • Overview
    • Blog
    • Apigee Institute
    • Academy
    • Documentation
  • Company
    • Overview
    • Press
    • Customers
    • Partners
    • Team
    • Events
    • Careers
    • Contact Us
  • Support
    • Support Overview
    • Documentation
    • Status
    • Edge Support Portal
    • Privacy Policy
    • Terms & Conditions
© 2019 Apigee Corp. All rights reserved. - Apigee Community Terms of Use - Powered by AnswerHub
  • Anonymous
  • Sign in
  • Create
  • Ask a question
  • Create an article
  • Post an idea
  • Spaces
  • Product Announcements
  • General
  • Edge/API Management
  • Developer Portal (Drupal-based)
  • Developer Portal (Integrated)
  • API Design
  • APIM on Istio
  • Extensions
  • Business of APIs
  • Academy/Certification
  • Analytics
  • Events
  • Hybrid
  • Integration (AWS, PCF, Etc.)
  • Microgateway
  • Monetization
  • Private Cloud Deployment
  • Insights
  • IoT Apigee Link
  • BaaS/Usergrid
  • BaaS Transition/Migration
  • Apigee-127
  • New Customers
  • Explore
  • Topics
  • Questions
  • Articles
  • Ideas
  • Members
  • Badges