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.

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.

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>

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'
  }
});

Allow permalinks into the Embed

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'
  ]
});

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'
  }
});

Loading Typekit

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

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();

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>