API or embed

The usual assumption is that embeds are for examples and the API is for anything serious. That is not the difference.

An embed can be driven from your page: set the code, run it, read back what the user wrote, and receive the output when it finishes. The API speaks both REST and WebSocket, so a program that prompts the user is reachable there too. Evaluation, exercises and interactive work are all possible either way.

The actual difference is who renders the editor.

• An embed

  We render the editor inside your page. You drive it from your own scripts and handle what comes back.

  Good for anything where a JDoodle editor in your page is what you wanted anyway.

• The API

  You render everything, or nothing. Code goes from your backend over REST for a result, or over WebSocket for a run you follow as it happens.

  Good for your own editor, a terminal, an interactive exercise, or a flow with no editor at all.

What follows from that

• Where the credentials live. An embed carries none, so nothing sensitive is in the page. The API's client ID and secret belong on your server, for an interactive run the browser gets a short-lived token instead, never the secret.
• How much you build. An embed is configured, not written. With the API the editor, the layout and the state are yours to build and maintain.
• How much you control. The embed looks like a JDoodle editor because it is one. The API looks like whatever you make.
• Whether you need a backend. An embed driven from the page needs no server of yours. The API needs somewhere to hold the secret and make the call.

Choosing

Start from the interface. If a JDoodle editor in your page is acceptable, an embed gets you there with less to build and no credential to protect. If the editor has to be yours, your keybindings, your layout, your file tree, then you are building it, and the API is what runs the code behind it.

What next

If the API is the right fit, one request shows the whole shape of it. If an embed is, Embeds covers building one.