What is the difference between an API and an embedded Domain Specific Language (DSL)?

Is it just syntax?

Consider an API like OpenGL. How is that different from a graphics DSL?

In other words, if an API is sufficiently complex, can it be considered an embedded DSL?

  • 1
    The point of a DSL is to make things simpler. Shouldn't you be asking if a sufficiently simple API could be considered a DSL?
    – Doval
    Commented Jul 31, 2014 at 13:50
  • I suppose what I want to know/understand is how are API and DSLs differentiated. I put complex in there because I figure that when one is constantly making calls to an API then it is rather domain specific, or at least that's how I originally thought about it. Commented Jul 31, 2014 at 13:57
  • 1
    The question is what is the difference between an API and an Embedded DSL?
    – proskor
    Commented Jul 31, 2014 at 14:14

5 Answers 5


The distinction is hard to make, and depend of the language used. It is also subjective.

In clojure, you can define APIs which look like a DSL. For exemple, hiccup allows you to generate html:

(html [:span {:class "foo"} "bar"])

This can be considered as a DSL with a lisp syntax. The fact that html could be a macro gives it the same amout of power as if you were writing a html templating lib with s-expressions (see sxml)

In python, the same API may look like:

html(["span", {"class" : "foo"}, "bar"])

html is a function. Its argument will be evaluated first, and then the function call will happen. The fact that the python syntax is more specific, and the python semantics are more strict means that this expression is harder to interpret as a DSL independent of the language.

A classic language representation is a tree like data structure and an eval function called recursively on its nodes. LISP languages makes this tree structure very apparent, so any nested function call is indistinguishable from a built-in language feature. That is why the LISP community speak about DSLs for almost everything.

I believe programming is about providing useful abstractions. I find that looking at everything you build (a lib or even the UI of your application) as language elements helping people to solve a complex problem is an effective way to design most things. With this perspective, I assert that every libraries are DSLs, but some of them are poorly designed :-)


APIs and DSLs are quite different concepts and there are only some areas where they might be said to overlap.

All DSLs are computer languages. They might be interpreted, compiled, mark-up, query languages (e.g. SQL) or (like JSON or some uses of XML) data languages which might used in messages passed over an API, but they must be languages. The term describes the nature, not the purpose.

APIs are interfaces allowing one software component to be used by other components. The term describes the purpose, not the nature. An API can be a set of object methods, for instance - that is not a DSL. A web API might use a DSL (or, if it is restful, you might argue that it is a DSL) but a shared, domain specific language is not part of the definition. A software driver for a device might be written in C, the API distributed as a compiled library, the protocol entirely binary and any language which can use the library might be used to make a client. Nothing in that API could be called a DSL (a list of symbolic names for the API functions does not cut it).

I'm a little confused as to why you can only see similarities, given the definitions.

  • As a commenter pointed out, I must have only considered embedded DSLs. Consider something like Forth where one builds a dictionary of words. I've read that as building a DSL as one gets close to having a feature complete application but it seems a lot like an API. Commented Jul 31, 2014 at 14:29
  • 2
    Which doesn't really affect my answer. If it is a language, with its own syntax etc, it's a DSL. A complex interface which lacks those language features is not a DSL. You should probably update your question and I will consider updating my answer.
    – itsbruce
    Commented Jul 31, 2014 at 14:35
  • 2
    A sublanguage is still a language. It is not necessary to have its "own" syntax, it can "borrow" it from the host language.
    – proskor
    Commented Jul 31, 2014 at 14:59
  • So then aren't all projects their own DSL when they are just about done (i.e. general programming languages are eventually DSLs)? A continuum of sorts from general to domain specific. Commented Jul 31, 2014 at 15:05

In general, no. A DSL is deliberately made non-general for the purpose of making some operations more convenient. Things like HTML or Logo were originally domain-specific languages.

In general, you can't embed a DSL into another language even with the most powerful API; whatever you program against that API will still look like a series of expressions in the host language and be not as convenient as using a special-purpose language would be.

The exceptions are languages that provide exceptional opportunities to warp the syntax via a library (operator overloading like C++, inventing new operators like Scala, or even predeclaring a completely different read syntax like Perl with source filters). When you use such a language and take full advantage of the flexibility they offer, then the result can look rather like a new, special-purpose language (but the semantics will often be subtly different from what you would expect if the language were really invented from the ground up to serve your ends).

  • So perhaps one could make a thing that parses a string (DSL) that acts as a simple wrapper for a large API. I suppose the separation of the DSL from the thing that parses the DSL is the differentiation. Commented Jul 31, 2014 at 14:00
  • 3
    Yes, that's called the "Interpreter" design pattern, and it's considered good practice: you write the interpreter code once, and from then on you can express your domain-specific content much easier. Commented Jul 31, 2014 at 14:09
  • "inventing new operators like Groovy" Perhaps you meant Scala; in Groovy the operator set is fixed but can be overloaded like in C++. Commented Sep 21, 2014 at 11:46
  • @VorgvanGeir Sorry, fixed. Commented Sep 21, 2014 at 11:47

Here, from DslBoundary by Martin Fowler

From the article, my understanding is basically embedded DSLs and APIs are not so difference. But however, there is a bit difference here.

  1. API emphasises on providing a new facility.
  2. DSL does not just provide you a new facility but provide you a new syntax and the new way to coding also.

But if talk about external DSL it will be another story. The external DSL is just like an small programming language but for sure, it is not a general-purpose language that mean it can not solve all the problems but specific problem instead.


I think every API is an embedded DSL but the converse is not true: not every embedded DSL is an API. Only when the language is used as a means to integrate components it can be called an API.

Why can an API be considered an embedded DSL? First of all, it forms a language: it has primitive elements (types and operations) which can be combined (by the means of the host language) to form abstractions and solve complex problems. For example, the OpenGL API can be used to render 3D-scenes in real-time. The Collections API can be used to create algorithms that operate on sets of objects, etc. Second, it is obviously domain specific; for example, the domain of the Collections API is handling sets of objects, and the domain of the OpenGL API is 3D rendering. Hence an API is a domain specific language.

But not every DSL is an API. For example, some DSLs are not to be implemented by a designated component. All systems define some abstractions, and the abstractions which deal with some specific domain can be considered a DSL, but that does not imply that the implementations of these abstractions should be "swappable", in other words, they do not have to form an API. They could, but that is not always necessary. However, in cases when the implementation is "componentized" (sorry for lack of a better term), the DSL indeed becomes an API.

  • is this merely your opinion or you can back it up somehow?
    – gnat
    Commented Jul 31, 2014 at 19:49
  • @gnat I extended my answer to further explain my point.
    – proskor
    Commented Jul 31, 2014 at 20:57

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.