locked
Naming service operations RRS feed

  • Question

  • Hi,

    I don't find a lot information about how to design your services, in particular how to name them, although I think it is very important. I have read that you should name your operations with business in mind and not CRUD operations:

    Example:
    - CreateOrder, DeleteOrder -> wrong
    - SubmitOrder, CancelOrder -> correct

    However, how would you design services that handle management of entities, for example the creation, retrieval, update and deletion of customers, countries and other elements? So, what would be the name of such service operations and also, what would be the return type?

    Example A:
    - Customer AddCustomer(Customer customer)   -> after creation, a Customer is returned with filled in key
    - Customer GetCustomer(long ID)
    - void SaveCustomer(Customer customer)
    - void RemoveCustomer(ID)

    Example B:
    - Customer SaveCustomer(Customer customer)   -> creates or updates the customer
    - Customer GetCustomer(long ID)
    - void RemoveCustomer(ID)


    Example C:
    - Customer CreateCustomer(Customer customer)  
    - Customer GetCustomer(long ID)
    - void UpdateCustomer(Customer customer)
    - void DeleteCustomer(ID)

    Or any other ideas?

    Summarized: I'm looking for best practises on how to name and design service operations, as well as what parameter and return types they should have.

    Tuesday, March 3, 2009 7:16 AM

Answers

  • Meanwhile I came up with another alternative, with following service operations:

    List<Customer> GetCustomers();
    List<Customers> SaveCustomers(List<Customer> customers);

    A Customer object has the usual properties like FirstName, LastName, Timestamp and so on, but also a TrackingInfo enum (Created, Updated, Deleted, Unchanged).

    Getting all customer is simply calling the service operation GetCustomers.
    Updating customers means updating the customer data and setting the TrackingInfo for that customer to Updated, and then call SaveCustomers passing the list of updated customers (1 or more).
    Deleting customers means setting the TrackingInfo for that customer to Deleted and then call SaveCustomers passing the list of deleted customers (1 or more).

    Of course the consumer can create, update and modify customers and process it in 1 SaveCustomers request. The dataaccess code takes care of the correct actions.

    This has to me the following advantages:
    - very simple service contract: you can do everything with two service operations
    - limit the amout to service calls
    - very flexible: consumer can send only what has been changed
    - consumer manages TrackingInfo

    Would like to have some feedback on this...

    Thanks!

    • Marked as answer by Yi-Lun Luo Monday, March 9, 2009 10:40 AM
    Monday, March 9, 2009 9:39 AM

All replies

  • Hello, name is not critical as long as it describes the operation without any doubt, and the users will be able to understand it without any problems. CreateOrder is not wrong. Some users may feel more comfortable with SubmitOrder, but others may prefer CreateOrder. For example, in .NET Services Access Control SOAP API, you'll find a lot of operations such as DeleteScope.


    Regarding your second concern, I think Example A is better. First, it provides a complete set of CRUD operations. Second, normally you don't need to return the updated entity, since the client already has the latest version. By using a one way operation, you can save the network traffic to some extend.


    Lante, shanaolanxing This posting is provided "AS IS" with no warranties, and confers no rights.
    Wednesday, March 4, 2009 11:31 AM
  • Meanwhile I came up with another alternative, with following service operations:

    List<Customer> GetCustomers();
    List<Customers> SaveCustomers(List<Customer> customers);

    A Customer object has the usual properties like FirstName, LastName, Timestamp and so on, but also a TrackingInfo enum (Created, Updated, Deleted, Unchanged).

    Getting all customer is simply calling the service operation GetCustomers.
    Updating customers means updating the customer data and setting the TrackingInfo for that customer to Updated, and then call SaveCustomers passing the list of updated customers (1 or more).
    Deleting customers means setting the TrackingInfo for that customer to Deleted and then call SaveCustomers passing the list of deleted customers (1 or more).

    Of course the consumer can create, update and modify customers and process it in 1 SaveCustomers request. The dataaccess code takes care of the correct actions.

    This has to me the following advantages:
    - very simple service contract: you can do everything with two service operations
    - limit the amout to service calls
    - very flexible: consumer can send only what has been changed
    - consumer manages TrackingInfo

    Would like to have some feedback on this...

    Thanks!

    • Marked as answer by Yi-Lun Luo Monday, March 9, 2009 10:40 AM
    Monday, March 9, 2009 9:39 AM
  • My only concern with your last example would be the reader quoters on the binding.  I use callbacks to return each entity, because eventually after a while of use the client may be retrieving more records than I had anticipated.  Similarly I only allow the updating of one record at a time.  This way I don't have to worry about the application hitting the quota limits a few years down the line.  It does make the contact large, but with code regions it is still organizable.
    Monday, March 9, 2009 4:32 PM