My thoughts on service naming conventions

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.


Hello Chris, You are just faster than me because I was also planning to post a blog on my blog. Here my thoughts: Use camel case for service names Within the Oracle tooling the use of '.' leads to errors. Don’t reveal implementation details in the service name That's indeed the whole purpose of a Service to hide the implementation details. Don’t include the word service in the service name It may be handy to be explicit. In logging you see what kind of resource you are delaing with (Service, JMS, ...) Remember services can have operations Indeed it can be handy to have a GetCustomer Service that has several operations, like GetCustomerByName, GetCustomerList etc. Also it makes sense because the different services may be used differently. And of course the naming of the Service is one thing, you also should consider the versioning issue of the Service: namespaces within WSDL, backwards vs forward compatibility, proxy naming and use within OSB, etc. But maybe that is a good item for a next post.

Posted by Roger van de Kimmenade on July 16, 2009 at 07:07 AM BST #

Hi Roger, Glad to hear you agree with most of these. Don't include the word service in the service name I see what you are saying here, but I'd still favour not including it unless its absolutely necessary. Remember services can have operations There are certain cases where it makes sense to have multiple services rather than use operations, e.g. in Oracle Service Bus if you want to set different different operational settings you'd need separate services as you can't define different settings per operation. Service versioning is another big topic which raises a lot of debate. To get you thinking about it, read Jeff Davies' chapter on Versioning Services from The Definitive Guide to SOA: BEA AquaLogic Service Bus which suggests the whole concept is flawed. As for proxy naming, I think the same rules apply as for service interface naming. The service consumer should not need to know the service is a proxy or that it is hosted on OSB. Good points though Roger.

Posted by Chris Tomkins on July 16, 2009 at 07:39 AM BST #

Post a Comment:
  • HTML Syntax: NOT allowed

UK Pre-Sales consultant specialising in business integration.


« November 2015