Hi,
would it make sense to add to harness API: GET /recipes/(recipe_id)/logs/(path) so harness could provide URL or content to test?
One of the requests in past was to be able to get to your own console.log, so you can for example check output of kdump kernel.
Regards, Jan
Excerpts from Jan Stancek's message of 2013-02-21 20:49:28 +1000:
Hi,
would it make sense to add to harness API: GET /recipes/(recipe_id)/logs/(path) so harness could provide URL or content to test?
One of the requests in past was to be able to get to your own console.log, so you can for example check output of kdump kernel.
Good idea, Jan. Thanks for the suggestion. I will add it to the doc.
It makes perfect sense as it matches PUT for the same URL. And it will be easy to implement if the logs are always on the LC while a recipe is running, which I want to do:
http://gerrit.beaker-project.org/1701
On 02/22/2013 08:31 AM, Dan Callaghan wrote:
Excerpts from Jan Stancek's message of 2013-02-21 20:49:28 +1000:
Hi,
would it make sense to add to harness API: GET /recipes/(recipe_id)/logs/(path) so harness could provide URL or content to test?
One of the requests in past was to be able to get to your own console.log, so you can for example check output of kdump kernel.
Good idea, Jan. Thanks for the suggestion. I will add it to the doc.
It makes perfect sense as it matches PUT for the same URL.
I was actually going to ask about that - is there any reason not to have GET counterparts for most of the URLs in the API? It would be nice not to have to go through the main XML-RPC API in order to read back results when testing a harness.
Cheers, Nick.
Excerpts from Nick Coghlan's message of 2013-02-22 12:25:03 +1000:
On 02/22/2013 08:31 AM, Dan Callaghan wrote:
Excerpts from Jan Stancek's message of 2013-02-21 20:49:28 +1000:
Hi,
would it make sense to add to harness API: GET /recipes/(recipe_id)/logs/(path) so harness could provide URL or content to test?
One of the requests in past was to be able to get to your own console.log, so you can for example check output of kdump kernel.
Good idea, Jan. Thanks for the suggestion. I will add it to the doc.
It makes perfect sense as it matches PUT for the same URL.
I was actually going to ask about that - is there any reason not to have GET counterparts for most of the URLs in the API? It would be nice not to have to go through the main XML-RPC API in order to read back results when testing a harness.
The recipe XML gives back everything that you can create or modify (status, results, logs, ...) so you can just use that.
But I agree, for completeness it might be nice to allow GETs on everything and return some kind of sensible response.
Excerpts from Dan Callaghan's message of 2013-02-22 12:51:31 +1000:
Excerpts from Nick Coghlan's message of 2013-02-22 12:25:03 +1000:
I was actually going to ask about that - is there any reason not to have GET counterparts for most of the URLs in the API? It would be nice not to have to go through the main XML-RPC API in order to read back results when testing a harness.
The recipe XML gives back everything that you can create or modify (status, results, logs, ...) so you can just use that.
Actually that's not true, it doesn't give back the complete logs (obviously) but it does not even give back a *listing* of which logs exist. There is a separate XML-RPC interface for that.
So yes, I will definitely add GET for fetching all the stuff back.
On that note, what are people's preferred ways of returning a listing of resources (e.g. GET /recipe/1234/logs/)? HTML, Atom, JSON array of hrefs, ...?
On 02/22/2013 12:54 PM, Dan Callaghan wrote:
Excerpts from Dan Callaghan's message of 2013-02-22 12:51:31 +1000:
Excerpts from Nick Coghlan's message of 2013-02-22 12:25:03 +1000:
I was actually going to ask about that - is there any reason not to have GET counterparts for most of the URLs in the API? It would be nice not to have to go through the main XML-RPC API in order to read back results when testing a harness.
The recipe XML gives back everything that you can create or modify (status, results, logs, ...) so you can just use that.
Actually that's not true, it doesn't give back the complete logs (obviously) but it does not even give back a *listing* of which logs exist. There is a separate XML-RPC interface for that.
So yes, I will definitely add GET for fetching all the stuff back.
On that note, what are people's preferred ways of returning a listing of resources (e.g. GET /recipe/1234/logs/)? HTML, Atom, JSON array of hrefs, ...?
For PulpDist, I used djangorestframework's content negotiation to publish human readable HTML, XML and JSON. I don't think we need to go that far - basic structured data as JSON files should suffice (and is the REST tradition).
While I don't agree with all the details, my general philosophical guide for RESTy APIs is this article written by one of the RHEV developers: https://restful-api-design.readthedocs.org/en/latest/
Alas, I don't have a public example of what I did for PulpDist to share with you, but I'll send you an RH internal one.
Cheers, Nick.
Excerpts from Nick Coghlan's message of 2013-02-22 13:12:49 +1000:
On 02/22/2013 12:54 PM, Dan Callaghan wrote:
On that note, what are people's preferred ways of returning a listing of resources (e.g. GET /recipe/1234/logs/)? HTML, Atom, JSON array of hrefs, ...?
For PulpDist, I used djangorestframework's content negotiation to publish human readable HTML, XML and JSON. I don't think we need to go that far - basic structured data as JSON files should suffice (and is the REST tradition).
While I don't agree with all the details, my general philosophical guide for RESTy APIs is this article written by one of the RHEV developers: https://restful-api-design.readthedocs.org/en/latest/
This advocates (or seems to advocate) inventing your own un-namespaced XML format for every collection type, which I think is a terrible idea, especially for what I am talking about here which is just returning a set of links to resources in a collection. If you like XML then at least a standard format like Atom is a nicer choice.
On 02/22/2013 01:17 PM, Dan Callaghan wrote:
Excerpts from Nick Coghlan's message of 2013-02-22 13:12:49 +1000:
On 02/22/2013 12:54 PM, Dan Callaghan wrote:
On that note, what are people's preferred ways of returning a listing of resources (e.g. GET /recipe/1234/logs/)? HTML, Atom, JSON array of hrefs, ...?
For PulpDist, I used djangorestframework's content negotiation to publish human readable HTML, XML and JSON. I don't think we need to go that far - basic structured data as JSON files should suffice (and is the REST tradition).
While I don't agree with all the details, my general philosophical guide for RESTy APIs is this article written by one of the RHEV developers: https://restful-api-design.readthedocs.org/en/latest/
This advocates (or seems to advocate) inventing your own un-namespaced XML format for every collection type, which I think is a terrible idea, especially for what I am talking about here which is just returning a set of links to resources in a collection. If you like XML then at least a standard format like Atom is a nicer choice.
Not really. The important is referencing other collections as something like:
"examples": { "_type": "link", "rel": "collection/examples", "url": "https://hostname/api/examples/" },
And individual resources as something like:
"example": { "_type": "link", "rel": "resource/example", "url": "https://hostname/api/examples/specific-example/" }
You *could* just use the bare URLs instead of moving them inside a namespace like that, but it gives you a lot more freedom to create self-describing data if you don't.
Cheers, Nick.
On 02/22/2013 01:31 PM, Nick Coghlan wrote:
You *could* just use the bare URLs instead of moving them inside a namespace like that, but it gives you a lot more freedom to create self-describing data if you don't.
To make this a little less abstract...
These would be the results for application/json. application/xml would only be supported for individual recipes, and would give the standard Beaker recipe XML
GET /recipes/ - list of all recipes in the recipeset - each entry includes the *full* representation that would be returned by a GET for that recipe
GET /recipes/1234/ - returns a JSON mapping, for example:
{ "_type" : "recipe", "url": "http://lab.controller.fqdn/api/recipes/1234/", "tasks": { "_type": "link", "rel": "collection/tasks", "url": "http://lab.controller.fqdn/api/recipes/1234/tasks/" }, "logs": { "_type": "link", "rel": "collection/logs", "url": "http://lab.controller.fqdn/api/recipes/1234/logs/" }, "remote-logs": { "_type": "link", "rel": "collection/remote-logs", "url": "http://lab.controller.fqdn/api/recipes/1234/remote-logs/" }, "watchdog": 8760 }
GET /recipes/1234/tasks/ - list of all tasks in the recipe - each entry includes the *full* representation that would be returned by a GET for that task
GET /recipes/1234/tasks/678/ - returns a JSON mapping, for example:
{ "_type" : "task", "url": "http://lab.controller.fqdn/api/recipes/1234/tasks/678/", "recipe": { "_type": "link", "rel": "resource/recipe", "url": "http://lab.controller.fqdn/api/recipes/1234/" }, "results": { "_type": "link", "rel": "collection/results", "url": "http://lab.controller.fqdn/api/recipes/1234/tasks/678/results/" }, "logs": { "_type": "link", "rel": "collection/logs", "url": "http://lab.controller.fqdn/api/recipes/1234/tasks/678/logs/" }, "remote-logs": { "_type": "link", "rel": "collection/remote-logs", "url": "http://lab.controller.fqdn/api/recipes/1234/tasks/678/remote-logs/" } }
If you insist on using a stateful non-self-describing design instead, then I *will* ask you to use a "/v1/" prefix as Bill suggested.
Cheers, Nick.
Excerpts from Nick Coghlan's message of 2013-02-22 14:03:29 +1000:
On 02/22/2013 01:31 PM, Nick Coghlan wrote:
You *could* just use the bare URLs instead of moving them inside a namespace like that, but it gives you a lot more freedom to create self-describing data if you don't.
To make this a little less abstract...
[...]
If you insist on using a stateful non-self-describing design instead, then I *will* ask you to use a "/v1/" prefix as Bill suggested.
Okay this is far more than I think we should add in the first version of the API, because: * it goes way beyond the goal of defining the "bare minimum" API needed for a harness implementation (I may have left that phrase out of the design proposal, but it was my original intention) * it is a fair bit of work writing the code to produce all this * designing JSON representations is apparently contentious, and a lot of work
So what I will add to the propsal is just: GET for the log files themselves, and GET for the logs/ and remote-logs/ collections returning an HTML index or an Atom feed.
Atom has a distinct content type (application/atom+xml) so that doesn't preclude us from adding this style of JSON and XML representations later on.
On 02/22/2013 02:53 PM, Dan Callaghan wrote:
Excerpts from Nick Coghlan's message of 2013-02-22 14:03:29 +1000:
On 02/22/2013 01:31 PM, Nick Coghlan wrote:
You *could* just use the bare URLs instead of moving them inside a namespace like that, but it gives you a lot more freedom to create self-describing data if you don't.
To make this a little less abstract...
[...]
If you insist on using a stateful non-self-describing design instead, then I *will* ask you to use a "/v1/" prefix as Bill suggested.
Okay this is far more than I think we should add in the first version of the API, because:
- it goes way beyond the goal of defining the "bare minimum" API needed for a harness implementation (I may have left that phrase out of the design proposal, but it was my original intention)
- it is a fair bit of work writing the code to produce all this
- designing JSON representations is apparently contentious, and a lot of work
So what I will add to the propsal is just: GET for the log files themselves, and GET for the logs/ and remote-logs/ collections returning an HTML index or an Atom feed.
Atom has a distinct content type (application/atom+xml) so that doesn't preclude us from adding this style of JSON and XML representations later on.
Sounds good to me. Perhaps add something to Deferred Features?
Cheers, Nick.
On 02/21/2013 09:54 PM, Dan Callaghan wrote:
Excerpts from Dan Callaghan's message of 2013-02-22 12:51:31 +1000:
Excerpts from Nick Coghlan's message of 2013-02-22 12:25:03 +1000:
I was actually going to ask about that - is there any reason not to have GET counterparts for most of the URLs in the API? It would be nice not to have to go through the main XML-RPC API in order to read back results when testing a harness.
The recipe XML gives back everything that you can create or modify (status, results, logs, ...) so you can just use that.
Actually that's not true, it doesn't give back the complete logs (obviously) but it does not even give back a *listing* of which logs exist. There is a separate XML-RPC interface for that.
Which I think is a bug, I just filed it here: https://bugzilla.redhat.com/show_bug.cgi?id=915319
So yes, I will definitely add GET for fetching all the stuff back.
On that note, what are people's preferred ways of returning a listing of resources (e.g. GET /recipe/1234/logs/)? HTML, Atom, JSON array of hrefs, ...?
Beaker-devel mailing list Beaker-devel@lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/beaker-devel
beaker-devel@lists.fedorahosted.org