An API creates its own ad hoc rules too. They just don't change the grammar.

In languages where the grammar is sufficiently flexible, the distinction all but disappears, but even in languages where the grammar is rigid and API's stand out like a sore thumb, the API itself still creates a new rule-set that you need to learn.

You can choose to not call that a new language all you want, but the cognitive load is still there.

An API (as people usually mean by it, anyway…) is really just a simple grammar for the creation and manipulation of objects in the system. Those objects still have types and properties just like any other object, but they tend to be implicit and unreliable. A good DSL is just a more abstract and implicitly verb-oriented API. For example, Lua DSLs can resemble something almost like a sort of typed or tagged DDL. Translating that into an “API” just adds more clumsy legwork to achieve the same outcome.

Agreed - I was tempted to make the same claim that it is still a grammar, but decided against it as I suspected it'd get in the way of making the point. You're 100% right you can write a grammar for an API as well, or can consider the API definition it self as creating a grammar.

I've seen it. Sometimes a DSL is more readable than trying to shoehorn control flow into method calls (".then().catch()..."). Or see C#'s LINQ.

> Or see C#'s LINQ.

This might be one of the rare times it's worth it. The C# team alread has the experience and tooling to maintain a language. Maintaining a DSL might be a reasonable choice for them.

It's rarely a good idea for app or library devs to make a similar decision.

Yes, this reminds me of meta-programming in languages like Python, it's useful if you want to create a framework like Django, but if you work on products, chances are good you should not use it.

There are plenty of places where it makes more sense to use DSLs (or where they’re flat-out required). SQL and regex both spring to mind. Pretty much any HTML templating language is simpler to use than concatenation a bunch of strings together. JSX is usually easier read than directly calling React functions directly. A line of a shell script can be much nicer (and more portable) than 20 lines of a more general purpose language.

Those are things that spring to mind that I think are unequivocally DSLs, but if you’re willing to consider markup languages as DSLs, the list could get a lot longer.

Most people think of DSLs as a language you can create within a language. All the things you named are either entire languages themselves like HTML, SQL, and the shell family, or formal extensions of existing languages like JSX. A DSL would be something you could create inside JS tagged literals or Ruby.

I don't think of DSLs as strictly being embedded in another programming language. The term I would use for that is "eDSL", short for Embedded Domain Specific Language. See: https://wiki.haskell.org/Embedded_domain_specific_language

Martin Fowler on DSLs, including internal and external DSLs:

https://martinfowler.com/books/dsl.html

https://martinfowler.com/dsl.html

Also see:

https://en.m.wikipedia.org/wiki/Domain-specific_language

including the References section.