Scenario Driven API Design

I am entrusted with the task of designing a new API for our flagship product Elcom's Community Manager

This New API was primarily intended to help clients to extend the community manager and use its feature rich cms functionality and help developers to reduce their development time.

API cannot be changed and any change would be a breaking change so OOP and other design patterns are not the best solution when it comes to designing api's.

I started the project by putting myself into the user shoes and there by writing code samples.

This scenario is called as Scenario driven design and is better suited to API development

Some of the guidelines of this design

1. Simplicity
Code Samples (start api design by writing code samples).

Structuring Hierarchial Namespace to organize information and enable people to find types.

Advanced and complicated scenario must be simplified if not better avoid them in the API.

Wise use of exceptions messages (Use exception messages to communicate framework usage mistakes to the developer)

Allow Progressively Learning for developer

2. Know your User

a. Think that User has very limited capability and make things easy
b. If user easily gets into trouble using the api then we have failed.
c. User should be able to start programming reading none or very little documentation
d. Create - Set - Call Pattern is preferred even by advanced developers so this should be the standard
. Create Instance using default empty constructor
. Set Properties
. Call Methods
e. Speak to the user and understand requiments (Requirements scoping)
f. Make other dev teams use the API and request feedback.

3. Think Development Ecosystem

Intellisense
Avoid Generic Names like message, element, log etc may cause ambiguous reference conflicts
Consistency (All Types should have a similar pattern)
No Hungarian casing like CMArticle , CMFolder etc.

Method vs Properties

Use Properties

If the member logical attribute of the type

Use Methods

If Order of execution is important use method

If member returns an array

If method might not return immediately