[katello-devel] Foreman API v2 guidelines and design

[Joseph Magen]

Hi all,

I am interested in hearing from you about the design and guidelines for best consuming the Foreman API v2.  Some questions are:

1) What to include when returning list of objects vs. single object?
2) 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)
3) 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