Does internal types compromise good API design?

Question

It seems to me that anytime I come across internal calls or types, it's like I hit a road block.

Even if they are accessible in code like open-source, it still feels they are not usable parts of the API code itself. i.e. it's as if they are discouraged to be modified.

Should one keep oneself from using the internal keyword unless it's absolutely necessary?

I am asking this for an open-source API. But still not everyone will want to change the API, but mostly use it to write their own code for the app itself.

Answer 1

An API is comprised of its public types and members, anything else is an implementation detail.

That being said, I think that internal types can be very useful especially when you want to return interface types from your API and don't want to expose the concrete types that you have used to implement those interfaces. This gives the API designer a lot of flexibility.

Answer 2

Internal types are types that are explicitly meant to be kept out of the API. You should only mark things internal that you don't want people to see.

My guess is that you're coming across types that are internal, but would have been valuable additions to the public API. I've seen this in quite a few projects. That's a different issue, though - it's really the same issue as whether a private type should have been public.

In general, a good project should have internal or private types. They help implement the required feature set without bloating the public API. Keeping the public API as small as possible to provide the required feature set is part of what makes a library usable.

Answer 3

There is nothing wrong with having an internal type in your DLL that is not a part of your public API. In fact, if you have anything other than a trivial DLL is more likely a sign of bad design if you don't have an internal type (or at least a non-public type)

Why? Public APIs are a way of exposing the parts of your object model you want a consumer to use. Having an API of entirely public types means that you want the consumer to see literally everything in your DLL.

Think of the versioning issues that come along with that stance. Changing literally anything in your object model is a breaking change. Having internal types allows you great flexibility in your model while avoiding breaking changes to your consumers.