1. API Design Tutorial
2. API Design: Lots of Upfront Design
3. API Design: Keep it Small and Focused
4. API Design: Don't Expose More than Necessary
5. API Design: Provide Sensible Defaults
6. API Design: Optional Abstractions
7. API Design: Central Point of Access
8. API Design: Don't Force the User to Assemble Components
9. API Design: Avoid External Dependencies
10. API Design: Avoid Logging in your APIs
11. API Design: Design for Testing
12. API Design: Design for Easy Configuration

• Think Code Completion
• Factories as Central Point of Access
• Managers as Central Point of Access
• Facades as Central Point of Access
• Service Proxies as Central Point of Access

As mentioned in the introduction one of the goals of an API is to make it as easy as learn as possible. One way to make it easy to learn is if you keep the number of classes down that the user needs to know before she can use the API. A way to achieve this is to provide a central point of access to the API.

My Java persistence API Butterfly Persistence has two central points of access to the API. The first one is the PersistenceManager. Almost no matter what you need to do with Butterfly Persistence, you start out by calling the PersistenceManager to obtain the second central point of access, an IDaos instance.

In this text I'll cover a few different techniques to provide a central point of access to an API. These are not the only techniques possible. Use your own sensible judgment to decide which technique is appropriate for your API.

Think Code Completion

One of the benefits of a central point of access is that the user of the API can browse the API using the code completion feature found in most IDE's. Once the user has learned how to access the central point of access the rest of the features can be browsed from there, often including the API docs. This means less need to constantly consult the documentation.

Factories as Central Point of Access

A factory class can be used as a central point of access. To do so, you would have a single factory from which you can access all objects of importance in the API. From each of the objects you obtain from this factory you should be able to access any objects not covered by the factory. How many layers you get in this call chain isn't really important. What matters is that you can browse the API using the code completion feature, starting from the factory.

Managers as Central Point of Access

In some API's it doesn't make sense to have a factory be the central point of access. Rather you want a class which is a combination of a factory and an object with some API behaviour.

The PersistenceManager in Butterfly Persistence is such a class. From the PersistenceManager you can obtain both a database connection or an IDaos instance, which internally has a database connection. You can have the PersistenceManager obtain the database connection, or you can pass the database connection to the PersistenceManager when you obtain the IDaos instance. Obtaining a database connection or an IDaos instance is mostly factory behaviour.

The PersistenceManager will get connection life time scoping and transaction scoping features in the future (these features are already present in Mr Persister from which Butterfly Persistence is derived). These features are not really factory features, but rather resource management features. Hence the class is called PersistenceManager and not PersistenceFactory even though it serves as a factory too.

Facades as Central Point of Access

Another way to provide a central point of access to an API is by providing a Facade (the design pattern) for the API. Rather than accessing all the classes of the API directly, the user will access the services provided by the API via this Facade class.

Providing a Facade can be handy if it is not possible or does not make sense to have a single central factory or manager class (well, a manager class can also be thought of as a kind of Facade). For instance, your API may have several different factories each responsible for creating part of the objects needed to perform the service the API provides. And, you might want to make it possible to replace factory implementations too. In that case it may not really make sense to have a central factory class.

Service Proxies as Central Point of Access

In a service oriented architecture (SOA) the central point of access for a service may be a service proxy. Jini uses intelligent service proxies as access point to Jini services, a SOAP client may auto-generate a service proxy from the WSDL of the service to access etc.

When you think about it, a service proxy is pretty similar to a Facade. So, whether you call your central point of access a service proxy or Facade isn't really that important. Use the name that fits best with your API and architecture.