How to define a good service interface | Division by Zero

Architecture, security and coding

How to define a good service interface

How to define a good service interface

Written by Division by Zero

Tuesday, 30 March 2010 09:54

The company I work at has a Service Oriented Architecture. Not every service we develop, maintain or use, has a good service interface. The problem with defining a good service interface is that you have to think well about what your service is going to do and what it's position in the application landscape is going to be. The service interface is a functional description of your service, herein lies the problem: most service interfaces are designed by technical people and based on a technical object model.

If I'm designing a service interface I always stick to the following rules:

Keep the interface functional. Instead of using "ID" to identify a customer, use "CustomerRelationNumber" or "CustomerIdentificationNumber". The first one is too generic, too technical.
Keep the interface as small as possible. More data means more interpretation. The more data you wish to send trough this interface the harder it will be to keep it simple and functional.
Define one service interface for one function. Separate different functional actions in different service interfaces. Don't do something like adding "Status" and return a customer if the status is 1 and return a company if the status is 2. Beside that it breaks rule 1, the service does different functional actions. Keep it simple, make the interface as comprehensible for other developers as possible.
Don't define too many interfaces. This rule struggles with rule 3. Think about your service and what data you really need. If you need too define a lot of interfaces for your service, maybe it does too many things?

The main goal of following these rules is to create a service interface which is understandable. If a developer needs to use your service it shouldn't be hard to know what the service does. If I need to use a service, I want to be able to easily send the data the service needs by reading a little about the context of the service, a little about the functionality of the service and the service interface.

Tags:

Related Articles

Add comment

I think, therefore I am. - R. Descartes

© 2009 - 2012, Division by Zero

Template based on the empire template by joomlashack

This work by Division by Zero is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Netherlands License.