Formal principles and processes for designing an API (C#)

Question

While I have some development experience, I have yet to design APIs or larger scale projects.

My general process usually involves something along:

1. Coming up with a few proposed designs.
2. Enlist their pros and cons.
3. Given a set of scenarios (X changes, new feature added, etc) -- how does the design react to it.

This is my own "style"; I am wondering where can i read more about formal processes and methodologies for doing such things? (online, books, etc)

Answer 1

The Framework Design Guidelines is a great book for this. Also, the .NET Framework Standard Library Annotated Reference is another great book.

Here's some of the principals I've followed:

• Less is more: taking away features makes users more productive more quickly as there are fewer concepts to learn. Less is more leads to a...
• Low barrier to entry: users expect to learn the basics of a new framework/API very quickly. They want to learn by experimentation and not by reading documentation. Most only take the time to fully understand a feature if it's particularly interesting or to move beyond basic scenarios
• Type names should be noun phrases: they represent entities of the system. Names should also represent scenarios. The most easily recognised names should be used for the most commonly used types, even if better better suited to a less commonly used type. The examples giving in the FDG book is Printer and PrintQueue, where Printer would be the most easily recognised but PrintQueue would better describe the concept. Which leads to...
• Concentrate on abstractions and not concepts. The examples used are the File base class in .NET and the derived NtfsFile. Most devs would automatically try to instantiate a File, only to discover it's abstract. Inheritance like this works well in implementation, but...
• Framework design is not the same as OO design: for example, in .NET there is a hierarchy of objects; Stream, StreamReader, TextReader, StringReader, and FileStream. There is a clear hierarchy but this is confusing when thinking of a scenario, e.g. reading a file.
• Assemblies represent packaging and deployment boundaries. Best practices (in .NET anyway) generally say that namespaces should match assemblies, e.g. MyCompany.MyTechnology.dll has a namespace MyCompany.MyTechnology and other namespaces, such as MyCompany.MyTechnology.MyFeature. This isn't necessarily applicable to Frameworks/APIs; the assembly here should represent logical grouping for devs and allow for performance (load time), easy deployment, and easy versioning. This is a balancing act; nobody likes referencing more than 1 assembly when just 1 will do. And nobody likes taking dependencies on stuff they don't need if an assembly is too big and has poor logical grouping (e.g. having to take an additional dependency on ADFS even if the features you're using in the API have nothing to do with ADFS).