Am 11.02.2015 um 14:23 schrieb Viliam Rockai <vrockai(a)redhat.com&gt;: Hi, I'm looking at hawkular-inventory and I've got several comments (liveoak legacy) which could apply on other rest endpoints, too: 1. I think it would be easier to use/get if we make it more hierarchical. That means; instead of using two distinct URLs (resources vs. resource) for lists (/hawkular/inventory/rest-test/resources/) and entities (/hawkular/inventory/rest-test/resource/x1422733176502), we use only one (/hawkular/inventory/rest-test/resources/x1422733176502).

2. Sometimes, in the docs, attribute called "name" is used, and referred to, as an "id". Would it be possible and make sense to choose just one notation and use it in the representation?

3. Usage of methods: When you want to create a metric, you use the PUT method. What about unifying methods in some commonly used manner. Like post for create, put for edit?

----- Original Message ----- > From: "Heiko W.Rupp" <hrupp(a)redhat.com&gt; > To: hawkular-dev(a)lists.jboss.org > Sent: Wednesday, 11 February, 2015 2:43:00 PM > Subject: Re: [Hawkular-dev] REST ideas > > > > Am 11.02.2015 um 14:23 schrieb Viliam Rockai <vrockai(a)redhat.com&gt;: > > > > Hi, > > > > I'm looking at hawkular-inventory and I've got several comments (liveoak > > legacy) which could apply on other rest endpoints, too: > > > > 1. I think it would be easier to use/get if we make it more > > hierarchical. That means; instead of using two distinct URLs (resources > > vs. resource) for lists (/hawkular/inventory/rest-test/resources/) and > > entities (/hawkular/inventory/rest-test/resource/x1422733176502), we use > > only one (/hawkular/inventory/rest-test/resources/x1422733176502). > > This is a good question/suggestion. I tried to follow the pattern of <foo>S > for list + creation > and <foo>/x for identifying individual objects - sort of like in natural > language. > > > > > 2. Sometimes, in the docs, attribute called "name" is used, and referred > > to, as an "id". Would it be possible and make sense to choose just one > > notation and use it in the representation? > > Yes. I think we may need some more overall cleanup as soon as we know > more about some terms and semantics we want to use. > > > > 3. Usage of methods: When you want to create a metric, you use the PUT > > method. What about unifying methods in some commonly used manner. Like > > post for create, put for edit? > Well, I am actually not so sure here. For some entities, like tenants themselves or environments, I think the URL pattern for creation could look like: /tenants/{tenantId} or /{tenantId}/environments/{environmentId} These guys are a little bit different because the USER supplies the ID. so we could have a POST like /tenants/?tenantId=asdf or an empty POST or PUT into /tentants/{tenantId} both tenant or environment are essentially non-updateable. I am no REST expert but an "empty POST" seems weird to me as does specifying the ID as an parameter in POST request. It is just my personal taste, but I find the PUT for creation here the most natural.

I am easily swayed though ;) > I guess you are right here. I used put instead of post for the metrics, as > they are > sort of dependent objects. > > > > Heiko > > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

| I am no REST expert but an "empty POST" seems weird to me as does specifying | the ID as an parameter in POST request. It is just my personal taste, but I | find the PUT for creation here the most natural. -1. PUT is for modifying and POST for creating new resources, that's the convention. That's what client writers would expect. The POST request doesn't have to be completely empty, there can be the id as Viliam had mentioned or in the future there can be additional fields. Let's listen to the wisdom of RESTafarians here :) http://www.restapitutorial.com/lessons/httpmethods.html jk _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

> Am 11.02.2015 um 14:23 schrieb Viliam Rockai <vrockai(a)redhat.com&gt;: > > Hi, > > I'm looking at hawkular-inventory and I've got several comments (liveoak > legacy) which could apply on other rest endpoints, too: > > 1. I think it would be easier to use/get if we make it more > hierarchical. That means; instead of using two distinct URLs (resources > vs. resource) for lists (/hawkular/inventory/rest-test/resources/) and > entities (/hawkular/inventory/rest-test/resource/x1422733176502), we use > only one (/hawkular/inventory/rest-test/resources/x1422733176502). This is a good question/suggestion. I tried to follow the pattern of <foo>S for list + creation and <foo>/x for identifying individual objects - sort of like in natural language.

> 2. Sometimes, in the docs, attribute called "name" is used, and referred > to, as an "id". Would it be possible and make sense to choose just one > notation and use it in the representation? Yes. I think we may need some more overall cleanup as soon as we know more about some terms and semantics we want to use. > > 3. Usage of methods: When you want to create a metric, you use the PUT > method. What about unifying methods in some commonly used manner. Like > post for create, put for edit? I guess you are right here. I used put instead of post for the metrics, as they are sort of dependent objects. Heiko _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

I'd like to bring 4. when returning collections from api. I think we should not stick with simply returning an array of objects. When we in future realize we need to include paging info or other helper data, we'd have to break the API and transform the response to somethine like

{ "result":[{....},{...}], "paging"... } Yes .. in case of paging, we can put it into HTTP headers, but for client it is much easier to reach paging info from the response. So simply wrapping returned array into response object does not hurt at all, brings consistency (data is always provided under same key "result") and extensibility. I can see this trend in other projects - Foreman's moved to this concept in REST APIv2, and ie. djangorestframework or Kodi. Libor Dne Wed, 11 Feb 2015 14:23:34 +0100 Viliam Rockai <vrockai(a)redhat.com&gt; napsal(a): > Hi, > > I'm looking at hawkular-inventory and I've got several comments (liveoak > legacy) which could apply on other rest endpoints, too: > > 1. I think it would be easier to use/get if we make it more > hierarchical. That means; instead of using two distinct URLs (resources > vs. resource) for lists (/hawkular/inventory/rest-test/resources/) and > entities (/hawkular/inventory/rest-test/resource/x1422733176502), we use > only one (/hawkular/inventory/rest-test/resources/x1422733176502). > > 2. Sometimes, in the docs, attribute called "name" is used, and referred > to, as an "id". Would it be possible and make sense to choose just one > notation and use it in the representation? > > 3. Usage of methods: When you want to create a metric, you use the PUT > method. What about unifying methods in some commonly used manner. Like > post for create, put for edit? > > WDYT? > > Viliam > > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev

Another REST issue we should agree on: The standard for error responses. I've found, that there are several standards we can follow (or create our own):

-----BEGIN PGP SIGNATURE----- Version: GnuPG v1 iQEcBAEBAgAGBQJU3gadAAoJECKM1e+fkPrXJS8H/3KgcizkKZekW+PZV4HpwlMo +9MPDMxtxnPtXq0o5GYTdEL3uRHVqRwMK04Fwx5dYJ+2bJQ9EXFK/hQhg0mWuHzh kSKGwBQD+zDb9IPHVUSKoYvkkXBcZjsQscYL6uNA/TiTp8pT+JxTw6aRkSylW/95 UOdC8aoEZQqGzOO2tBcwiIoF7TXa+tVuY5TgV/ldydBCbQgPl2/iQY++Mwj4h6ri VEacrDoGe0sNrrEMOJf4YvyCXgkVWdeaviscZ816LQ2dKFU4CocgY/0IeGwlwz9F IDevKUWqbrj+UXSjZoUh+p2+7dSJyjob2jfHev+TayC7nlbj6/TrSmTK0t7O7qg= =r0UU -----END PGP SIGNATURE-----