Adam,
To see an example of Foreman API v2, you can view the branch https://github.com/isratrade/foreman/tree/3491_v2
Note that this is not merged yet in Foreman 'develop' branch.
I'm using architectures as a basic CRUD example. Go to /api/architectures (with version=2 in header) and you should see something like this
{
"total": 4,
"subtotal": 4,
"page": 1,
"per_page": 20,
"search": null,
"sort": {
"by": null,
"order": null
},
"results": [
{
"name": "i386",
"id": 2,
"created_at": "2010-08-15T10:15:27Z",
"updated_at": "2010-08-15T10:15:27Z"
},
{
"name": "Sparc",
"id": 3,
"created_at": "2012-01-02T15:42:28Z",
"updated_at": "2012-01-02T15:42:28Z"
},
{
"name": "armv5tel",
"id": 8,
"created_at": "2012-07-16T09:19:16Z",
"updated_at": "2012-07-16T09:19:16Z"
},
{
"name": "x86_64",
"id": 1,
"created_at": "2010-08-15T10:15:27Z",
"updated_at": "2013-09-03T14:34:45Z"
}
]
}
If you go to /api/architectures/2, you should see
{
"architecture": {
"name": "i386",
"id": 2,
"created_at": "2010-08-15T10:15:27Z",
"updated_at": "2010-08-15T10:15:27Z"
}
}
Note: TBD is the root_name will go away or it will be called something else.
Architecture has 3 has_many relationships, so we plan to add the following 3 nested routes, but this is not ready yet
api/architectures/:id/hostgroups
api/architectures/:id/images
api/architectures/:id/operatingsystems
Also, we may include none, one or all of the relationship data in the 'show' response. It's dependent on each object.
I used a RABL layout to show the metadata on each :index action. See https://github.com/isratrade/foreman/blob/3491_v2/app/views/api/v2/layouts/index_layout.json.erb
{
"total": <%= @total.to_json %>,
"subtotal": <%= @subtotal.to_json %>,
"page": <%= @page.to_json %>,
"per_page": <%= @per_page.to_json %>,
"search": <%= @search.to_json.html_safe %>,
"sort": {
"by": <%= @by.to_json.html_safe %>,
"order": <%= @order.to_json.html_safe %>
},
"<%= "#{@root_node_name}" %>": <%= yield %>
}
In Api:V2::BaseController, I have two callbacks to get the instance variables for the layout above.
Note, that I added the gem 'rails3_before_render' to get the method before_render.
before_filter :root_node_name, :only => :index
before_render :get_metadata, :only => :index
layout 'api/v2/layouts/index_layout', :only => :index
The Rabl templates for architectures are found at https://github.com/isratrade/foreman/tree/3491_v2/app/views/api/v2/architectures
If interested, there is also a Rabl initializer at https://github.com/isratrade/foreman/blob/3491_v2/config/initializers/rabl_init.rb
that was needed for v2, since we couldn't change the global Rabl default settings. If we did, it would break v1.
Basic functional tests for the api v2 architecture controller is at https://github.com/isratrade/foreman/blob/3491_v2/test/functional/api/v2/architectures_controller_test.rb
I tested the metadata response only in one controller (locations) that you can see at https://github.com/isratrade/foreman/blob/3491_v2/test/functional/api/v2/locations_controller_test.rb#L86
I hope that helps. Let me know if you have any questions.
Regards,
Joseph