-
We don’t have API versioning today, so if we don’t make the default behavior backward compatible we break existing integrations for every API change we make. This is going to be a bigger and bigger issue as more people integrate with Foreman. We shouldn’t just tell them to rewrite every time we make API changes. This is not best practice for API design.
-
By using html headers, to call an API version, we can add the header call from the client, and older servers will just ignore it.
-
I envision that the latest version of foremancli, should work with older versions of foreman, as there are going to be environments that need to work with multiple foreman servers running different versions of foreman. I know we have a difference of opinion here, in that you only want to suport the latest version of foreman with RemoteAdmin. As this project matures we are going to see more and more people running older versions of Foreman longer than we might necessarily like, and I want to support that with the tools I am working on. (Basically I feel that for foremancli, it should support versions of foreman going back to 0.4 where it was introduced. Hammer will likely be coded to the 0.5 API, but likely won’t make the 0.5 ship.)
When following REST principles, APIs shouldn’t break backwards compatibility. Being that this is the real world, and we don’t have a large set of resources to get this all right from the gitgo, we are going to need to make changes that aren’t compatible. One way to support this is through API versioning. However, from everything I have been researching embedding API version in the URI in any form, doesn’t follow REST design principles. Using a version header seems to be the best option.
The one question is if you call the URI without the version header, which version of the API do you default to? Generally speaking the thought is to respond with the latest version, unless API versioning wasn’t part of the API from the beginning. IE: If you didn’t initially provide API consumers with the capability to lock clients to a specific API version, you shouldn’t break the default behavior.
Thanks,
Brian
On Thu, Apr 19, 2012 at 6:01 PM, Corey Osman corey@logicminds.biz wrote:
I suppose you could add a param to the API call
http://foreman/hosts?format=json&apiversion=042
then in the format.json branch just add a condition to check for the apiversion param and use the old method.
Otherwise, how many people would this affect? Is it too much to ask the users to update the foremancli gem?
format.json {
if params[:apiversion] == "042"
render :json => search.all(:select => “hosts.name”, :include => included_associations).map(&:name)
else
should you ever need more attributes just add to the :only array or specify :methods, :include, :except to the options hash
format.json { render :json => search.includes(included_associations).to_json({:only => [:name, :id, :hostgroup_id, :operatingsystem_id]}) }
end
}
Corey Osman
corey@logicminds.biz
Green IT and Datacenter Automation Specialist
On Apr 19, 2012, at 2:28 PM, Brian Gupta wrote:
So I just upgraded our foreman instance to from 0.4.2 to latest develop branch, and there seems to be a significant change in how the API outputs the default hosts collection.
Previously, it outputted a text hostlist as the default output, and a semi-useless json list of hosts if you requested JSON output. Now it seems the default is JSON, and it is a more correct JSON output that includes: name:, id:, hostgroup_id:, and operatingsystem_id:.
This breaks the default behavior of foremancli --hosts, which previously output a text list of hosts, that was very easy to parse with classic shell scripting.
Any thoughts on how to get back the old foremancli behavior? (Ideally, I would be able to get the old behavior via API versioning, but am open to additional thoughts.)
This is pretty important, because this functionality is the main reason I wrote foremancli in the first place. (A simple text host list.) All the other stuff, I added was to make it more useful to other people.
Thanks,
Brian
–
–
