Geeks With Blogs
SOA & Integration Services - BizTalk, WCF, WF, AppFabric etc Why is it drug addicts and computer afficionados are both called users?

I come across this problem a lot. I often get work to fix problems that largely stem from bad interface design.

Architects know how important interfaces are whether they be WSDL, C# interfaces, stored procedure parameters etc. Developers in my experience should get a grip on this stuff. 

Once you have some requirements spending some quality time working out what your interface is important. Developers need to hammer this into their skulls, it's pritty simple. This isn't an exhaustive post but try and follow these simple steps for good interface design (as I'm doing WSDLs at the moment so the examples will be WSDL\Xsd Schema interfaces). Please feel free to feed back your agreements\disagreements other posts which are better etc...

1) You need a list of requirements to start i.e. data fields, 1 to many relationships, min and max occurrences, business rules and how these fields should be used.

2) Ask what are the important pieces of data here i.e. if you are writing a document delivery system, the document is probably the parent and will be closer to the root of your xsd schema how, where, why, what is delivered will come under that.

3) Group common data elements together. If your document delivery system needs to email and fax documents create a common schema type called DeliveryChannel or something and put ALL the email and fax data elements in there. Maybe look up on line for some example generic\flexible schemas that deal with address information and copy them or get ideas. Good xsd design is a big topic and I won't cover it here.

4) You should now have made a start i.e. a schema that is a best attempt with what you know so far.

5) TEST YOUR INTERFACE: this isn't code testing, your interface might just be on a bit of paper at this stage it doesn't matter. I can think of two tests the interface must pass:

  1. The interface must be able to implement your business requirements, trick them off one at a time.
  2. The interface must work with existing and future interfaces which need to call it and it will need to call find out what the data fields, min and max occurrences, business rules are for the api's, components or services that will use your interface or your interface will use. Create an excel spreadsheet and map this stuff.

6) Modify your interface when it fails these tests until it passes them.

7) Finally check you don’t have redundant fields, the schema is flexible enough for the future BUT NOT RIDICULOUSLY GENERIC and related data is in the same place not littered throughout.

Try to do this or something similar at the very least before you rush in and start coding.

Posted on Tuesday, February 21, 2012 11:36 AM General | Back to top

Comments on this post: Developers need to understand interfaces, interfaces, interfaces!

# re: Developers need to understand interfaces, interfaces, interfaces!
Requesting Gravatar...
I'd like to amend #5 to include, if your API is public, publish your tests too. As an API consumer I want to see what your own expectations are and verify that your tests are passing.

A few weeks ago I started using API from a company that required that *I* write unit tests demonstrating that I understood how to use their API before I could be allowed access. That was bizarre.

Regarding redundant fields, I once used a trading API that returned the entire Account entity every place I really only needed AccountNumber. Calling GetTradesForAccount(#) would return 1000 trades and 1000 copies of the Account too. :(
Left by Ryan on Feb 21, 2012 6:52 PM

Your comment:
 (will show your gravatar)

Copyright © Rob Addis | Powered by: