I am trying to write an angular service to interface with a RESTful API.
For sake of simplicity, lets assume the API is
+ Company
|___+ Department
| |____ Person
|
|____ Person
Notice how person can be under
Company > Departmentor directly underCompany.
Each of the entities (Company, Department and Person) support add, edit, list and get_by_id.
Which of the following interfaces is more idiomatic?
Option 1:
// In all cases, get(), put() return $http promise
companyApi().get() // List all companies
companyApi(1).get() // Get company with ID 1
companyApi(1).departments().get() // List all departments
companyApi(1).departments(2).get() // Get department with ID 2
companyApi(1).departments(2).persons().get() // List all persons
companyApi(1).departments(2).persons().put(p) //Add a new person in department 2
companyApi(1).persons().put(p) //Add a new person in company 1
companyApi(1).persons(3).put(p) //Edit person with ID=3 in company 1
companyApi(1).persons(1).remove(p) // Delete a person
Option 2:
// In all cases, get(), put() return $http promise
// List all companies
companyApi({
type: 'company'
}).get();
// Get company with ID=1
companyApi({
type: 'company',
companyId: 1
}).get();
// Get department with ID=2 under company 1
companyApi({
type: 'department',
companyId: 1,
departmentId: 2
}).get();
// List persons under department with ID=2 under company 1
companyApi({
type: 'person',
companyId: 1,
departmentId: 2
}).get();
// Get person with ID=3 under department with ID=2 under company 1
companyApi({
type: 'person',
companyId: 1,
departmentId: 2,
personId: 3
}).get();
// Get person with ID=3 under department with ID=2 under company 1
companyApi({
type: 'person',
companyId: 1,
departmentId: 2,
personId: 3
}).get();
// Add person under department with ID=2 under company 1
companyApi({
type: 'person',
companyId: 1,
departmentId: 2,
}).put(personObj);
//Edit person with ID=3 in company 1
companyApi({
type: 'person',
companyId: 1,
departmentId: 2,
personId: 3
}).put(personObj);
// Add person under directly under company 1
companyApi({
type: 'person',
companyId: 1
}).put(personObj);
First of all, whatever you do, please use unique ids. In your current scheme you can only reference an entity through the exact path through the tree, that is generally annoying to work with. What happens if a person is moved from one department to another? Or if there is a department restructure? Nothing will retain its handle.
Second, don’t make entities that basically work the same way different. Company, department and any other organisation entity is just a container in your data model, there is no reason to distinguish between them in your basic data model.
The simplest way of implementing a tree structure is to make a data table with the fields id and parentId and have the parentId of any row be the id of its parent.
You can of course make a host of different functions to interface this data, you could start out with something like:
get(id)
getChildren(id)
getChildrenIds(id)
getDescendants(id)
create(parentId, ...)
move(id,newParentId)
9