Payloads with transient data

[Jeffrey Haynes]

Several of our endpoints on my company's API require what I call transient information in the payload, typically for a POST operation. This data describes things that are required when creating the object, but are not persisted.

How would you handle that?

I/we have some ideas here, but I'd like to hear opinions from this forum.

Thanks,

Jeff

[Chris Mullins]

Hi Jeff,

I don't think I understand what you're asking. 

If a POST operation requires data for the create operation, even if that data isn't saved as part of the operation itself, it seems it would be part of the JSON payload passed to the REST API. The fact that data passed to the operation is, or is not, saved to some persistent state store seems immaterial. 

Am I missing something obvious in your question? 

Cheers,

Chris

[Jeff Haynes]

Hi Chris,

Thanks for your answer. I can see that I need to add some details to the question.

We know that there are no constraints on the payload from a persistence perspective. The question has to do with modeling the data. We are wondering what ideas that API community has about the implementation and representation of objects in the system where the create and/or update payloads are different from what is returned in a query.

We think that if the objects are different, then there could be confusion from the client's perspective.

For example, we have an Account object defined as:

Account: 

String account_num;

String name;

...

But in addition to the details of the account object, we also need to provide a way to specify a boolean attribute named "autoBill". But this attribute is not persisted and is not returned in a query for an Account.

We are wondering how others have handled this. If we include this in the payload, the client will wonder why they can't get it back in a query (they can read the docs, but there seems to be a moe intuitive way)

We could create a separate payload, but that doesn't really resolve the differences between the query and create payloads.

One thing that I am proposing is to provide an optional object on all create/update requests named "config" or something that would allow for this type of detail.

What problems are there with this approach? And what have others done to resolve this? Is there an API design issue here?

Thanks  

Jeff

--
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/YiuulpZQBUY/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.

[Kijana Woodard]

What does "autoBill: true" mean to the server?

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.

[Jack Repenning]

On Dec 1, 2015, at 6:59 AM, Jeff Haynes <jeff9...@gmail.com> wrote:

But in addition to the details of the account object, we also need to provide a way to specify a boolean attribute named "autoBill". But this attribute is not persisted and is not returned in a query for an Account.

I'm guessing that "autoBill" actually is persisted somewhere, just not in the same table as your ordinary data, like "name." 

POST /path/to/things

{

    "name" : "Fred",

    "autoBill" : true

}

==> 201 { "id" : 237 }

GET /path/to/things/237

==> 200 { "name" : "Fred" }

In that case, my reflex is to say, "yes, your resources are improperly designed." A "thing" is an API "data transfer object," a "resource," meaningful at the API interface but not necessarily anywhere else, and it either does, or does not, have an "autoBill" field. There is no requirement that this DTO resource exactly match any internal persistence representation (table schema). In simple cases, they often do, but complex cases where they don't abound. Your resource design should be about simple, comprehensible, resource patterns, not internals. The resource abstraction exists precisely to free you to have different internal representation -- even to refactor the internals at need -- without disturbing clients.

-- 
Jack Repenning
Repenni...@gmail.com

[Cooper Marcus]

Are you saying that when you POST to create a resource you include an attribute that is NOT included in the response to a GET for that just-created resource?

If so, I'd concur with Jack, and I think you could do this better.

I'd suggest (though I have no idea if this is strictly correct in all cases) that the response to GET'ing a resource must include all the things that were included in the POST that created that resource.

--

You received this message because you are subscribed to the Google Groups "API Craft" group.

To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.

[Jørn Wildt]

POST is for "do what you want with this payload" => calculate and store the sum of included values then return that (and the moon phase too) with GET from the same URL - or some other different URL. Anything, It really doesn't matter. POST is the generic "do stuff with the payload".

PUT is expected to replace (or create) the target resource with the included payload. The returned resource representation does not have to include everything PUT to it and it may also add stuff to it (like for instance links or "last updated" timestamps), but the underlying resource is expected to be replaced completely with the payload.

POST is often interpreted as "add this to the collection at the URL" but does not have to be so. POST can also be used for command like patterns where you POST a request of some sort to be processed by the resource - some people do not find this "RESTful" but you really cannot judge "RESTfulness" by a single request - its the overall use of resources, URLs as identifies, status codes and hypermedia that together forms a "RESTfully" designed distributed system.

/Jørn

[Jeffrey Haynes]

Jørn,

Thanks for your comment.

Most of the time when we need to use a  "transient" payload is when we have a command or action to perform - something like "activate", "suspend" or  "deactivate".

Usually these requests need a date or some other "extra data" to perform the action.

So, it seem totally reasonable to use payloads that aren't persisted in these cases.

I'd like to hear comments on this though.

Thanks

 Jeff

[Kijana Woodard]

What's the connection between persistence and what is required by the API?

Those are separate concerns.

Further, I'm not aware of a restriction that would prevent

POST /accounts

{

  "name" : "Fred",

 "autoBill" : true,

 "somethingTransient" : 999

}

==> 201 { "id" : 237 }

GET /accounts/237

==> 201 { "id" : 237, "name" : "Fred", "somethingServerGenerated": "interesting info" }

GET /accounts/237/billing-settings

==> 201 { "id" : 237, "autoBill" : true }

Visit this group at https://groups.google.com/group/api-craft.

[Adrian Lynch]

Marcus, would you suggest the same thing for the other way around? A GET /resource with more fields than the POST /resource?

Adrian

[Jørn Wildt]

I'm not Marcus, but anyway :-)

> A GET /resource with more fields than the POST /resource?

Yes, sure! You don't POST "created date" to a resource but you wouldn't be surprised to GET it back, right? It is also possible to POST data for a single resource and then GET back that resource together with some embedded data from other related resources.

/Jørn

Visit this group at https://groups.google.com/group/api-craft.

[Adrian Lynch]

Exactly!

So why not the other way around?

I've just seen Marcus works for New Relic, cool!