Formal API design principles and processes (C #)

Question

Although I have some development experience, I have yet to develop APIs or large-scale projects.

My general process usually involves something:

• Coming up with several proposed projects.
• Take advantage of your pros and cons.
• Given a set of scenarios (X changes, new features added, etc.) - how the design responds to it.

This is my own "style"; I wonder where I can learn more about formal processes and methodologies for such activities. (online, books, etc.)

Answer 1

I like The Clean Coder, as well as Agile Principles, Patters and Practices in C #, and finally Clean Code, written by Robert C. Martin. I like the way he writes, I like his coding style, and he gave me subtleties to think about and relate to my professional career as a programmer. You can get all of these books for pretty cheap on Amazon. Also, Robert C. Martin has his own website for these kinds of things. http://www.objectmentor.com/omTeam/martin_r.html is the website in which it is presented in the section "About our part of the team." hustle there and see if you can find his other site, and a program he wrote called Fitnesse.

Despite the fact that your style looks good for projects with a normal size, which, as a rule, amateurs have on a large scale, this can be a few more steps. What kind of online service were you thinking of writing? I am currently writing another for Zoho, but all the time I forget to import my code from work into my program.

Answer 2

The wireframe design guide is a great book to do this. In addition,. The .NET Framework Annotated Reference is another great book.

Here are some of the principles that I followed:

• Less is more : disabling features makes users more productive faster because less concepts are needed for training. Less leads to more ...
• Low barrier to entry : users quickly learn the basics of the new infrastructure / API. They want to learn by experimenting, not by reading documentation. Most only need time to fully understand the function if it is especially interesting or go beyond the basic scenarios.
• Type names must be nouns of phrases : they represent the essence of the system. Names should also represent scripts . the most easily recognized names should be used for the most commonly used types , even if they are better suited for the less common type. Examples in the FDG book are Printer and PrintQueue , where Printer will be most easily recognized, but PrintQueue better describe the concept. That leads to...
• Focus on abstractions, not concepts . Examples are the .NET base class File and the NtfsFile derivative. Most developers will automatically try to create an instance of File , only to discover its abstract . Inheriting how this works well in implementation, but ...
• The frame design is not the same as the OO design : for example, in .NET there is a hierarchy of objects; Stream , StreamReader , TextReader , StringReader and FileStream . There is a clear hierarchy, but it is confusing when you think of a scenario , for example. reading a file.
• Assemblies represent packaging and deployment boundaries . Best practices (in .NET anyway) usually say that namespaces should match assemblies, for example. MyCompany.MyTechnology.dll has a namespace MyCompany.MyTechnology and other namespaces such as MyCompany.MyTechnology.MyFeature . This does not necessarily apply to Frameworks / API; the assembly here should provide a logical grouping for developers and provide performance (boot time), easy deployment, and easy version control. This is a balancing act; no one likes to reference more than 1 assembly when only 1 will do. And no one likes taking dependencies on what they don’t need if the assembly is too large and has poor logical grouping (for example, you need to have an additional dependency on ADFS, even if the functions that you use in the API have nothing to do with ADFS) .

Answer 3

I just finished writing an API for one of our projects at work, and I have a few points.

The methodologies are great in principle, but think about your requirements. Will you develop several developers and support the API in the future, or are you primarily responsible for the development? If it is his first, then a structured methodology and process for architecture will pay dividends in the future when it comes to a (terrible, but inevitable) change.

If this is the last, then you have more flexibility. Each API is trying to achieve something else, whether it be a plug-in infrastructure or a "public" entry point to your service. I would recommend collecting some requirements and determining if one of the methodologies benefits you.