Embed icon

How to host Apiary documentation on your subdomain using Embed

With a simple JavaScript you can embed and customize your API Project on your domain.

Your own domain

Your own domain

Host Interactive API Documentation on your domain, customize its features and placement.

Your branding

Your branding

With powerful theming options, you can customize the look and feel of the docs.

This feature is exclusive to Apiary Standard & Pro Plans.

Apiary Embed docs comes with a single integration and JavaScript API.

This way, you can show your always up-to-date API Documentation on your developer portal, styled with your colors and custom font themes.

Embed documentation comes with an Interactive API Documentation, Mock server, Code examples and more.

1
Paste script into your page

You can place this is before </body> tag.

<script src="https://api.apiary.io/seeds/embed.js"></script>

2
Generate embed code

3
Read Apiary Embed API reference

Apiary Embed API Reference

Apiary Embed allows you to embed API Documentation on your domain, anywhere into your page and with your options and theme. It is a JavaScript file, that after loading into the page exposes a single Apiary object.

iOS support

Due to an issue in iOS WebKit, Apiary Embed is disabled on all iOS devices. A message with a link to view the documentation on Apiary.io is shown instead.

Basic options

Specify API Project

Basic use of Apiary Embed needs only a single option: which project to show.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi'
});

Use subdomain option, where subdomain is API Project subdomain, that can be changed in the API Project settings.

Changing API Project subdomain

When you change subdomain in the project settings, you also need to update the embed code.

Note

Customers integrating with Apiary over Integration API can use uuid instead of subdomain. uuid is not affected by subdomain changes.

Specify the HTML element for the embed

By default, embed takes over the whole browser viewport. You can control position of the embed by specifying the element option as a DOM selector e.g. #my-embed or div.my-embed. Embed will respect the dimensions of the element.

<div id="embedHere"></div>

<script>
  var embed = new Apiary.Embed({
    subdomain: 'pollsapi',
    element: '#embedHere'
  });
</script>

It is also possible to have multiple embeds on single page contained within the specified elements. When using this setup it is recommended to allow permalinks for only one of those embeds.

<div id="embedHere1"></div>
<div id="embedHere2"></div>

<script>
  var embed1 = new Apiary.Embed({
    subdomain: 'pollsapi',
    element: '#embedHere1'
  });

  var embed2 = new Apiary.Embed({
    subdomain: 'pollsapi',
    element: '#embedHere2',
    preferences: {
      permalinks: true
    }
  });
</script>

Alternatively, you can also add a header for a full-screen embed. Just specify the DOM selector for you header and embed will load it on top of it.

<header id="customHeader">My Logo</header>

<script>
  var embed = new Apiary.Embed({
    subdomain: 'pollsapi',
    header: '#customHeader'
  });
</script>
Note

It’s not possible to use the header option in conjunction with the element option.

Preferences

preferences object allows you to control behavior of API Documentation.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  preferences: { // Defaults, all optional
    console: true, // Allow console, set to `false` to disable
    collapseMachineColumnByDefault: false, // Collapse the machine column by default
    displayUriParametersInHumanColumn: false, // Display URI parameters
    displayHttpMethods: false, // Display names of HTTP methods
    fluidHumanColumn: false, // Human column takes 100% width
    permalinks: false, // Allow linking into the embedded API Project
    defaultHost: 'mock'
  }
});

Setting permalinks option to true will enable deep linking into embed docs. It does it by adding fragments with hash to the URL e.g. #/introduction/media-types. Don’t enable it if your application is using location hash for something else (like navigation in any JavaScript Single Page Application). More details about permalinks in the Interactive Documentation.

Modifying hosts

Available hosts are mock, proxy and production. You can read more about these hosts used in the Interactive Documentation.

Changing default host

You can change defaultHost for any of the available hosts. If production is not available because you didn’t provide HOST in your API Blueprint Embed will fallback to mock.

Modifying available hosts

Use hosts array to specify available hosts:

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  preferences: {
    defaultHost: 'production'
  },
  hosts: [
    'proxy',
    'production'
  ]
});

Code examples

Hiding code example languages

With codeExamples option you can control which code examples will be shown, by default, all are allowed:

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  codeExamples: {
    cUrl: true, // cURL
    javaScript: true, // JavaScript
    nodeJs: true, // Node.js
    python: true, // Python
    php: true, // PHP
    ruby: true, // Ruby
    c: true, // C#
    visualBasic: true, // Visual Basic
    groovy: true, // Groovy
    objectiveC: true, // ObjectiveC
    java: true, // Java
    go: true, // Go
    perl: true, // Perl
    swift: true // Swift
  }
});

Enabling only some languages

At the same time, you can also choose to allow only some code examples:

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  codeExamples: [ // Allows only Go and Swift code examples
    'go',
    'swift'
  ]
});

Apiary Embed - allow code examples

Custom fonts

customFonts option is used for loading 3rd party fonts into Apiary Embed. These fonts can be then applied with theme option - more on theme.

Loading self-hosted fonts

Use absolute URLs to load fonts. If possible, supply multiple formats for better cross-browser compatibility - woff format should cover +90% of users.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  customFonts: {
    families: [
      {
        name: 'Proxima Nova',
        style: 'normal',
        weight: 200,
        formats: [
          {
            format: 'woff',
            url: 'https://mycdn.com/fonts/proxima-nova/light.woff'
          },
          {
            format: 'truetype',
            url: 'https://mycdn.com/fonts/proxima-nova/light.ttf'
          }
        ]
      }
    ]
  },
  theme: {
    fontFamily: 'Open Sans'
  }
});

Loading Google Fonts

This example adds an Ubuntu from Google Fonts and applies it with theme.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  customFonts: {
    googleFonts: 'https://fonts.googleapis.com/css?family=Ubuntu'
  },
  theme: {
    fontFamily: 'Ubuntu'
  }
});
Note

Always make sure to use the HTTPS link instead of the HTTP one offered by default.

Loading Typekit

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  customFonts: {
    typekit: {
      kitId: '<KIT-ID>'
    }
  },
  theme: {
    fontFamily: 'Grafolita Script'
  }
});
Note

Make sure to allow jsapi.apiary.io domain.

Theming

For theming your documentation, we expose a JSON tree of objects/elements to which you can assign CSS properties.

How to

Targetting elements

You always need to address a full path to the element you want to style - e.g.

var embed = new Apiary.Embed({
  subdomain: 'pollsapi',
  theme: {
    machineColumn: { // To change color of a title in Machine Column
      content: {
        blankSlate: {
          title: {
            color: '#85144b'
          },
        }
      }
    }
  }
});

Elements with a state

Elements starting with $ describe a state - like $selected, $hover or $odd. Or in some cases HTTP methods like $get or $put.

Elements

Below you can find list of available styling elements - there are 3 main parts: Table of Contents (left), Human Column (middle) and Machine Column (right).

Table of Contents


tableOfContents
- section
-- title
--- $hover
--- text
---- $hover
-- item
--- $hover
--- $selected
--- $selected$hover
--- text
---- uriTemplate
----- slash
----- variable
----- queryVariableKey
----- queryVariableValue
--- subitems
---- subitem
----- $hover
----- $selected
----- $selected$hover
----- subitem
------ text
------- uriTemplate
-------- slash
-------- variable
-------- queryVariableKey
-------- queryVariableValue

Human Column


humanColumn
- wrapper
- content
-- apiName
--- $hover
-- section
--- title
---- $hover
---- text
--- resourceGroups
---- resourceGroup
----- name
----- resources
------ resource
------- name
-------- uriTemplate
--------- slash
--------- variable
--------- queryVariableKey
--------- queryVariableValue
------- description
------- actions
-------- action
--------- invitation
---------- $hover
---------- $selected
---------- $selected$hover
---------- text
---------- method
---------- tag
----------- $connect
----------- $copy
----------- $delete
----------- $get
----------- $head
----------- $lock
----------- $mkcol
----------- $move
----------- $options
----------- $patch
----------- $post
----------- $proppatch
----------- $put
----------- $trace
----------- $unlock
----------- $update
---------- icon
--------- description
--- apiDescription
--- Section Description ↝
- header
-- button
--- icon
-- breadcrumb
--- container
---- item
----- $section
----- $item
----- $subitem

Machine Column


machineColumn
- Code examples ↝
- content
-- URI Parameters ↝
-- blankSlate
--- title
--- text
---- actionExample
--- link
---- text
-- breadcrumbs
--- container
--- line
--- resourceGroup
--- resource
--- action
--- slash
-- destination
--- container
---- method
----- $connect
----- $copy
----- $delete
----- $get
----- $head
----- $lock
----- $mkcol
----- $move
----- $options
----- $patch
----- $post
----- $proppatch
----- $put
----- $trace
----- $unlock
----- $update
---- protocol
---- host
---- uriTemplate
----- container
------ slash
------ variable
------ queryVariableKey
------ queryVariableValue
-- title
--- text
-- request
--- name
--- description
---- Section Description ↝
--- controls
---- hosts
----- button
------ value
---- codeExamples
----- button
------ value
---- spacer
---- tryButton
-- response
--- name
--- statusCode
--- description
---- Section Description ↝
- console
-- blankSlate
--- title
--- text
--- link
-- breadcrumbs
--- line
--- resourceGroup
--- resource
--- action
--- slash
-- form
--- destination
---- container
----- method
------ $connect
------ $copy
------ $delete
------ $get
------ $head
------ $lock
------ $mkcol
------ $move
------ $options
------ $patch
------ $post
------ $proppatch
------ $put
------ $trace
------ $unlock
------ $update
----- protocol
----- host
----- uriTemplate
------ container
------- slash
------- variable
------- queryVariableKey
------- queryVariableValue
--- tabs
---- buttonGroup
----- item
------ $selected
--- tab
--- parameters
---- list
----- parameter
------ column
------ nameColumn
------ valueColumn
------ name
------ value
--- body
---- textarea
--- headers
---- list
----- header
------ key
------- input
------ value
------- input
---- addHeaderButton
----- p
--- buttons
---- reset
----- button
------ text
---- submit
----- button
------ text
- header
-- closeButton
--- icon
-- consoleButton
--- button
---- text

Components

Some repeating and nested parts were moved to standalone components/parts - Section Description, URI Parameters, Code Examples. In order to style these, you need to update all of its occurrences.

Section Description


p
- strong
- em
- $hover
- a
-- $hover
h1
- $hover
h2
- $hover
h3
- $hover
h4
- $hover
h5
- $hover
h6
- $hover
a
- $hover
- $link
- $visited
- $active
strong
- $hover
em
- $hover
hr
- $hover
img
- $hover
blockquote
- $hover
code
pre
- $hover
- code
-- $hover
ul
- $hover
- li
-- $hover
-- strong
-- em
-- a
--- $hover
ol
- $hover
- li
-- $hover
-- strong
-- em
-- a
--- $hover
table
- $hover
- thead
-- $hover
- tbody
-- $hover
- tfoot
-- $hover
- tr
-- $odd
-- $hover
-- td
--- $hover
-- th
--- $hover
del
ins
abbr
mark
sup
sub
kbd

URI Parameters


parameters
- title
- list
-- parameter
--- $required
--- $optional
--- column
---- icon
---- tooltip
--- key
--- type
--- description
---- Section Description ↝
--- example
---- code
--- default
---- code
--- values
---- invitation
----- icon
---- container
----- text
----- list
------ value
------- text
------- delimiter

Code examples


codeExample
- lineNumber
- line
-- comment
-- prolog
-- doctype
-- cdata
-- punctuation
-- namespace
-- property
-- tag
-- boolean
-- number
-- selector
-- attrName
-- string
-- operator
-- entity
-- url
-- keyword
-- regex
-- important

CSS properties

Properties List of allowed CSS properties.

Embed property CSS Property
background background
backgroundClip background-clip
backgroundColor background-color
backgroundImage background-image
backgroundOrigin background-origin
backgroundPosition background-position
backgroundRepeat background-repeat
backgroundSize background-size
border border
borderBottom border-bottom
borderLeft border-left
borderRadius border-radius
borderRight border-right
borderTop border-top
color color
display display
font font
fontFamily font-family
fontSize font-size
fontStyle font-style
fontVariant font-variant
fontWeight font-weight
margin margin
marginBottom margin-bottom
marginLeft margin-left
marginRight margin-right
marginTop margin-top
padding padding
paddingBottom padding-bottom
paddingLeft padding-left
paddingRight padding-right
paddingTop padding-top
textDecoration text-decoration
textDecorationColor text-decoration-color
textDecorationLine text-decoration-line
textDecorationStyle text-decoration-style
textShadow text-shadow
visibility visibility

We translate these properties and apply them to the Embed docs before rendering.

Event hooks

Embed instances provide event hooks. To fully harness the power of Embed you need to know which event hooks are available, in what order are these hooks called, and what is available during these calls. The event hooks have a direct relationship to the overall Embed lifecycle.

onLoaded

The event is fired when the IFrame inside Embed and its dependent resources have finished loading. This doesn’t necessarily mean that you can already interact with the embed documentation. This event is always fired before onReady.

  var embed = new Apiary.Embed({
    subdomain: 'pollsapi',
    element: '#embedHere'
  });
  embed.onLoaded(function (iframeElement, event) {
    // manage your loading indicator here
  });

onLoaded callback parameters

Name Type
iframeElement HTMLIFrameElement
event Event

onReady

The event is fired when the embeded documentation is ready to be interacted by the user. This event is always fired after onLoaded.

  var embed = new Apiary.Embed({
    subdomain: 'pollsapi',
    element: '#embedHere'
  });
  embed.onReady(function (iframeElement, event) {
    // manage your loading indicator here
  });

Un-subscribing

Even hooks can be un-subscribed. Every subscription returns a function. When this function gets called then the hook handler is immediately un-subscribed and will no longer be called.

  var embed = new Apiary.Embed({
    subdomain: 'pollsapi',
    element: '#embedHere'
  });
  const unsubscribe1 = embed.onReady(function (iframeElement, event) {
    // manage your loading indicator here
  });
  const unsubscribe2 = embed.onReady(function (iframeElement, event) {
    // manage your loading indicator here
  });

  // un-subscribes subscription(1)
  // subscription(2) is still active
  unsubscribe1();
Note

All event hook handlers are automatically un-subscribed when calling the destroy() method on Embed instance.

onReady callback parameters

Name Type
iframeElement HTMLIFrameElement
event MessageEvent

Destroying embeds

Embed instances can be destroyed. Destroying restores the element to the state before Embed was initialized.

<div id="embedHere"></div>

<script>
  var embed = new Apiary.Embed({
    subdomain: 'pollsapi',
    element: '#embedHere'
  });

  // destroy the embed some time later
  embed.destroy();
</script>