My thoughts on service naming conventions
By Chris Tomkins on Jul 16, 2009
Customers frequently ask me “What naming conventions should I use for my services?” The problem is there isn’t really a right or wrong answer. However, let me share a few of my thoughts based on my customer experience which I hope you’ll find useful:
Use camel case for service names
Service names are often used by tooling to generate associated artifacts, e.g. JMS queues or endpoint URIs, or on platforms where spaces or special characters are not permitted so I highly recommend using camel case (e.g. EachWordStartsWithACapitalLetter) to name your services as this removes the need for these characters while retaining the readability.
Don’t reveal implementation details in the service name
This not only has the potential to lead to confusion if you decide to change the implementation of the service, but is also a security risk as it gives the service consumer an insight into how the service may be implemented which they may be able to exploit.
Don’t include protocol information in the service name
This is generally unnecessary as the service advertises itself at a particular endpoint which clearly defines the protocol to be used.
Don’t include the word service in the service name
Would you add the word Class to every Java class you define? I’m guessing not. So why add the word service, its unnecessary.
Don’t include a version in the service name
Including the version number in the name of the service can also be a recipe for disaster. What happens when you decide to change the service? If the change is major and includes modifying the interface, then you will probably be happy to rename the service and inform all your service consumers of the new service endpoint. However, if the change is minor, do you really want to have to inform all your service consumers of this? If not, the same service name may actually refer to multiple versions of the service – very confusing!
Make sure the name of the service is something sensible
Sounds obvious enough, but I’m sure many of us have seen services called ABCService before! Naming a service like this is a bad idea for 2 reasons. Firstly, no-one is going to have any idea what the service does and so they are not going to reuse it (one of the key benefits of SOA). Secondly, if something goes wrong naming your services sensibly can aid problem diagnosis as you may be able to identify the problem area by just the name itself.
I have to admit, I like Thomas Erl’s suggestion of using utility-centric (e.g. Notify), task-centric (GetProfile) and entity-centric (Customer) names – read more about this in the Service Labelling section of his article on Standardizing Service Endpoints.
Remember services can have operations
This is not true for all services, but many types of service, e.g. web services, can include operations which can be used to group together related functions. I’d argue it makes more sense to have a single Customer service with operations such as get, add, remove, update rather than 4 services called GetCustomer, AddCustomer, RemoveCustomer and UpdateCustomer.
Operation names don’t need to include the service context or parameters
I regularly see operation names along the lines of getCustomerByCustomerID. Now if this is an operation on the Customer service taking in an ID parameter and returning a Customer then I’d argue calling the operation get is sufficient.
By no means is this a definitive list nor do I suggest you have to follow these conventions in your organisation, however I feel it’s a good starting point. I’d be interested to hear your thoughts on the ideas above and other naming conventions in use in your organisation.
It’s also worth noting, these naming conventions only apply to the service interface and this alone is unlikely to be sufficient to define your service fully. You should also consider defining one, or more, service contracts (typically human readable documents) which describe:
- What your service does
- Behaviour characteristics
- Any security requirements
- Performance characteristics
- Quality of service
- Usage charge
These documents should then be stored alongside your service interface definition in your enterprise repository.