Hi all,
I am interested in hearing from you about the design and guidelines for best consuming the API v2. Some questions are:
- What to include when returning list of objects vs. single object?
- When to return child/parent relationship objects vs. return child/parent id's only vs. return child/parent id's and name's vs. don't return child/parent details (as it can be returned in separate call)
- When to include timestamps "created_at, updated_at" in each response. Is this information used?
For the sake of discussion, let's take hostgroups. The current v1 response for a list of hostgroups AND a specific hostgroup is the same. It includes all database fields including parent_id's (domain_id, evironment_id, subnet_id, operatingsystem_id), plus array of child id's (for puppletclass), plus child objects (for parameters). I don't know if all this information is necessary for each call. Would it be better to break it done in minimal responses that will be quicker.
V1) same response for /api/hostgroups AND /api/hostgroups/8. No nested routes.
"hostgroup": {
"name": "PG-Database",
"environment_id": 1,
"subnet_id": 1,
"label": "Base/PG-Database",
"puppetclass_ids": [
1,
6,
5,
100,
77,
229
],
"operatingsystem_id": 6,
"ancestry": "1",
"domain_id": 6,
"parameters": {
"test_pg_param": "111"
},
"id": 8
}
V2) minimal responses depending on api call
/api/hostgroups - returns list of hostgroups with minimal response (id, name, label)
/api/hostgroups/8 - returns database fields of hostgroup id 8 (same as v1, but without puppetpclass_ids and parameters in response)
/api/hostgroups/8/puppetclasses - returns puppetclass objects of hostgroup id 8
/api/hostgroups/8/parameters - returns parameter objects of hostgroup id 8
/api/hostgroups/8/domain - returns domain object of hostgroup id 8
/api/hostgroups/8/environment - returns environment object of hostgroup id 8
/api/hostgroups/8/operatingsystem - returns operatingsystem object of hostgroup id 8
/api/hostgroups/8/subnet - returns subnet object of hostgroup id 8
/api/hostgroups/8/ancestor_ids - returns array of hostgroup ids in ancestry of hostgroup id 8
/api/hostgroups/8/otheraction - any other action
Note: /api/hostgroups/8/domain would return the same response as /api/domains/6
Regards,
Joseph