-
Notifications
You must be signed in to change notification settings - Fork 5
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
update @url and @model properties #19
Comments
I think assuming all I am not sure about only allowing model for message bodies, however. I like that it removes duality in using the property (makes things much easier to reason about) but leaves a void in functionality, possibly? URITemplate doesn't have the level of functionality that model does. Model allows rich support of describing forms, correct? And forms can be GET or POST/PUT. If we don't allow using models for GET, how will we be able to define labels etc. for GET forms? URITemplate doesn't really allow that, does it? Am I missing something badly? |
couple things:
|
You are right: the two cannot be used together, currently, so my bad on that one URITemplate is super convenient for GET because all major platforms have highly optimized parser implementations (even PHP has a C extension) but: how would you document placeholder parameters in URITemplate for a client? Meaning: the labels of those params, maybe some constraints? On Fri, Apr 3, 2015 at 8:18 PM, Mike Amundsen notifications@github.com
|
"how would you document placeholder parameters in URITemplate for a client?" how is that done in UBER now? |
I think UBER's So saying that Or am I missing something? (I'm intentionally ignoring the |
Right, ignoring the stalled template proposal for now.... As you say, In the current UBER spec:
Right now, without addressing the |
Right, yeah, cool. I think your line of reasoning about making {
"uber": {
"version": "1.x",
"data": [
{
"rel": ["self"],
"url": "http://api.example.com/"
},
{
"name": "list friends",
"rel": ["http://example.com/rels#list_friends"],
"url": "http://api.example.com/{user_id}/friends",
"action": "read"
},
{
"name": "search friends",
"rel": ["http://example.com/rels#search_friends"],
"url": "http://api.example.com/{user_id}{?name,page,per_page}",
"action": "read"
},
{
"name": "add friend",
"rel": ["http://example.com/rels#add_friend"],
"url": "http://api.example.com/{user_id}/friends",
"action": "append",
"model": "friend={friend_id}"
}
]
}
} Doing manual URI Template expanding, of course, I could... $ # Follow the self link...
$ curl "http://api.example.com"
$ # Assuming I already have some user ids handy for whatever reason,
$ # I could list someone's friends...
$ curl "http://api.example.com/1234/friends"
$ # Or search their freinds...
$ curl "http://api.example.com/1234/friends?name=mike" # default paging stuff
$ # Or, lastly, make an introduction...
$ curl -d "friend=7889" "http://api.example.com/1234/friends" Seem legit? I'm guessing, by the way, on how |
yep -- all looking good. that last example cuts right to the heart of it all, right? |
You are right, there's not "official" way of doing it. I will open an issue about that, but it's a completely separate thing. This proposal of using URITemplate for "read" and only using models for body is 100% great. Since there seems to be no doubt remaining, in principle, can we talk about the details please?
|
I think you might be underestimating the applicability of URI Templates. See my above example of "add friend" to see a case where you'd want to use a URI Template with a
Ugh. I hadn't considered that. I agree, then, that we should have a way to indicate whether a given |
@benhamill yeah, you skillfully avoided the trap in your example :), but I am asking about the cases in which URITemplate will be used for query params (which may still not be our problem, this is just a question). Re: templated thing, there is another option: since we are introducing new attribute, anyway, we might as well introduce |
yeah - when i write up the url/model PR this weekend, i'll include a i can definitely see cases where i want BOTH in the same request. HTML doesn't does this, but lots of other APIs do. |
If we go with |
excellent point. will make sure to include "false" as the default. |
i've updated the docs for issue #19 (+url+ and +model+ and +templated+) check it out and let me know what you think. i might do some clean up before creating the PR |
Awesome! Do you mind if I go ahead and create a PR? Makes it much easier to review changes. I can label it "pending review fixes" to mark as "not ready for merge" and any changes you make to the branch will show up automatically, anyway. |
done! |
made changes as suggested. let me know if you see any other needed mods. |
@inadarei
currently the
model
property is supposed to be used to modify theurl
property (whenaction="read"
) and for creating a BODY (whenaction="append|partial|remove|replace"
).i propose the following:
url
property MUST ALWAYS be treated as a UriTemplate[1]model
property MUST ONLY be used to construct the message BODYquestion:
url
as a template? that might be lots of needless work/processingtemplated="true|false"
property to apply to theurl
(whentrue
theurl
MUST be processed as a UriTemplate)comments?
NOTE: this will be a BREAKING CHANGE since old clients will MAY not treat the
url
ormodel
properties correctly[1] https://tools.ietf.org/html/rfc6570
The text was updated successfully, but these errors were encountered: