locked
Generic\abstract API vs specific API? which is best? RRS feed

  • Question

  • Hi

    In our company,we have several applications which manage different
    entities which conceptually related(not with any means of data base relations etc...)

    for example consider first application which manage cars,
    second which manage plains, and third which manage boats.

    All applications can produce a report which display the amount
    of cars, planes and boats, where all the properties of an entity is displayed on a report

    All Entities(cars, boat and plain) derived from a common class.
    And Provide a collection of properties

    DomainObject
    {
    Property[] GetProperties();
    }

    Where  a property  defined

    Class Property
    {
       Object value;
       PropertyDescriptor descriptor;
    }


    Also all applications supports creation of a new entity, while the entity may requires different initialization parameters.

    A requirement is to create an API so first application can use entities from  second and third application and vice versa

    While i am suggesting to create a very specific API,for example

    for the application which manage boats

    Boat createBoat(string Name,Point size,int price);
    Surfboard createSurfboard(string CompanyName,int price)

    for application  who create Cars

    Car createCar(string Name,Point size,int price,Color color,string Manufacturer);
    Motorcycle createMotorcycle(string company,int price);

    Some suggest that we should use an API which is as generic\abstracted as possiblefor example, they suggeststo create a general factory which can create ANY entity

    DomainObject create(DomainObjectType type,object[] parameters);

    Or a function which unite all possible parameters  which an application needs in order to create a report:

    DomainObject[] generateReport (ReportType type,param1,param2,param3,param4,param5);

    Where in  some cases we need to pass 'null' in param4,5 since the  entity does not need themIn this example First application will use parmeter 1 and parameter 2
    And second application will use parameter 1,2,3,4

    The main arugment of those who supports abstracted API,is that we can create a UI
    which is totally un aware of the  differences between the applications
    The user can enter the parameters (either for boat. Plain or cars) the programmer  will need to extract
    the properties out of the form
    And pass them to the function,also if an application introduce new type of domain object,nothing will
    need to be changed.Using reflection it can be done very quickly


    While I see the advantage for such approach , in some scenarios like reporting,data binding,anemic
    domain model

    I think  it is harder for a programmer to use such an API,we loosing intelisense
    We loosing compile type checking, I don’t think validation can be done on layer which is different than the Bll layer,I think we are going to see a  lot of casting in the code etc...

    What do yout think?

    Thanks in advance

     

     

     

     


     

    Tuesday, February 2, 2010 4:15 PM

Answers

  • I guess I was trying to differentiate -

    In your case, if your always going to be working with the same database, and trying to work on cars, planes, and boats, I would just directly make concrete types.

    If you're trying to make something that will be a general purpose layer, usable by anybody (ie: if this is a tool oriented towards developers working on a different set of domain classes), then it might make sense to go more abstract.  However, in this case, I'd still put a concrete API in place for each specific domain entity.

    Say, for example, you're making a general purpose data access layer, you may need to keep things very generic.  This is how DataSet/DataTable in ADO.NET is, for example.

    If, however, you're trying to access a specific corporate database, and expose the types to developers, having a concrete API for those types will dramatically lessen the learning curve for the developers, and will also make the development experience better all around.



    Reed Copsey, Jr. - http://reedcopsey.com
    • Marked as answer by אורצ'וק Wednesday, February 3, 2010 11:23 AM
    Tuesday, February 2, 2010 10:24 PM

All replies

  • I, personally, always prefer to use more concrete types, when possible.

    Abstracting away all of the type information is useful for framework development, but if you do that, it helps to provide a concrete type implementation on top of your abstract information.

    As you mentioned, a completely abstracted object model causes all sorts of other problems, most of which lead to a dramatic drop in developer productivity.  It's nice to develop in a type-safe, clean manner - and abstracting away all of your type safety just leads to lots of difficult to maintain code.



    Reed Copsey, Jr. - http://reedcopsey.com
    Tuesday, February 2, 2010 7:52 PM
  • Thanks Reed,

    1.What do you mean when saying 'framework development' , i thought that an API is too a  framework?!

    Tuesday, February 2, 2010 9:29 PM
  • I guess I was trying to differentiate -

    In your case, if your always going to be working with the same database, and trying to work on cars, planes, and boats, I would just directly make concrete types.

    If you're trying to make something that will be a general purpose layer, usable by anybody (ie: if this is a tool oriented towards developers working on a different set of domain classes), then it might make sense to go more abstract.  However, in this case, I'd still put a concrete API in place for each specific domain entity.

    Say, for example, you're making a general purpose data access layer, you may need to keep things very generic.  This is how DataSet/DataTable in ADO.NET is, for example.

    If, however, you're trying to access a specific corporate database, and expose the types to developers, having a concrete API for those types will dramatically lessen the learning curve for the developers, and will also make the development experience better all around.



    Reed Copsey, Jr. - http://reedcopsey.com
    • Marked as answer by אורצ'וק Wednesday, February 3, 2010 11:23 AM
    Tuesday, February 2, 2010 10:24 PM