0

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 > Department or 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);
1

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)
  • Note that the id there really should be a URI rather than just plain integer ID. Note that URI is not necessarily a URL. – Lie Ryan Aug 13 '14 at 14:36
  • @LieRyan Your comment lacks reasoning. What relevant purpose does an URI (however you define that term) serve, which a locally unique integer doesn't. It is easy to construct an URI scheme from the integers, but it is not necessary for local data manipulation. – aaaaaaaaaaaa Aug 13 '14 at 15:04
  • The namespace of a URI is universal (or application wide) unlike a local integer ID which has no context. If your identifier can point to anything in the tree, it need to be unique within the tree, which means you need an artificial id anyway. If you design a REST systems right, your objects most likely already have a URI/URN/URL, so it can be used as opaque identifier that can be dereferenced in generic way. In any case, generic methods like get, getChildrem, create, move, etc doesn't need to know if it is dealing with employee or company or what not, as long as it quacks like a duck. – Lie Ryan Aug 13 '14 at 15:38
  • @LieRyan I cite the very first sentence of my answer: "First of all, whatever you do, please use unique ids.". You seem to confuse the terms URI and unique id. A URI is a type of unique id, but there is no need for these unique ids to conform to a URI scheme. – aaaaaaaaaaaa Aug 13 '14 at 15:55
  • No, I'm not confusing them, I'm saying you should just use a URI rather than int id. The issue is that you need to invent a unique int id anyway, since the existing object id is probably not unique, as they originate from different types of objects. Rather than deal with mapping integer id in one space with another integer id in multiple other namespaces, using the object's URI will make your life much easier. The other fine alternative is to not use id, but just pass in the object and duck type, but that doesn't make sense for methods like get(id). – Lie Ryan Aug 13 '14 at 16:30

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.