Overview

Support and Learning Resources

• Learning Resources

• Product Support

• Why Aspose.HTML for .NET?

Aspose.HTML offers individual HTML processing APIs for other popular development environments as listed below:

API Blueprint Specification

Author: z@apiary.ioVersion: 1A9

Format 1A revision 9

I. API Blueprint Language

• Blueprint section

II. Sections Reference

Abstract

Section Basics

Going Further

III. Appendix

Introduction

This documents is a full specification of the API Blueprint format. For a lessformal introduction to API Blueprint visit theAPI Blueprint Tutorial or check some of the examples.

API Blueprint

API Blueprint is a documentation-oriented web API description language. TheAPI Blueprint is essentially a set of semantic assumptions laid on top of theMarkdown syntax used to describe a web API.

In addition to the regular Markdown syntax, API Blueprint conforms to theGitHub Flavored Markdown syntax.

API Blueprint document

An API Blueprint document – a blueprint – is a plain text Markdown documentdescribing a Web API in whole or in part. The document is structured intological sections. Each section has its distinctive meaning, content andposition in the document.

General section definition and structure is discussed in detail later in theBlueprint section chapter.

All of the blueprint sections are optional. However, when present, a sectionmust follow the API Blueprint document structure.

Blueprint document structure

• 0+Resource sections
  • 0-1Model section
  • 1+Action sections
    • 0+Request sections
    • 1+Response sections
• 0+Resource Group sections
  • 0+Resource sections (see above)

NOTE: The number prior to a section name denotes the allowed number ofthe section occurrences.

NOTE: Refer to Sections Reference fordescription of a specific section type.

Blueprint section

A Section represents a logical unit of an API Blueprint. For example: an APIoverview, a group of resources or a resource definition.

In general a section is defined using a keyword in a Markdown entity.Depending on the type of section the keyword is written either as a Markdownheader entity or in a list item entity.

A section definition may also contain additional variable components suchas its identifier and additional modifiers.

NOTE: There are two special sections that are recognized by theirposition in the document instead of a keyword: The Metadata section andthe API Name & Overview section. Refer to the respective section entryfor details on its definition.

Example: Header-defined sections

NOTE: While this specification uses 'atx'-style headers (using #s) you can also use 'Setext' header syntax interchangeably:

Example: List-defined sections

NOTE: While this specification uses pluses (+) as list markers you canuse any Markdown list syntax using asterisks (*), pluses (+) andhyphens (-) interchangeably:

Section types

There are several types of API Blueprint sections. You can find the completelisting of the section types in theSection Reference.

The Blueprint section chapter discusses the section syntax in general.A specific section type may conform only to some parts of this general syntax.Always refer for respective section reference for details on its syntax.

Section structure

A general structure of an API Blueprint section defined by a keywordincludes an identifier (name), section description and nestedsections or a specifically formatted content.

Example: Header-defined section structure

Example: List-defined section structure

Keywords

Following reserved keywords are used in section definitions:

Header keywords

• Group
• Data Structures
• HTTP methods (e.g. GET, POST, PUT, DELETE..)
• URI templates (e.g. /resource/{id})
• Combinations of an HTTP method and URI Template (e.g. GET /resource/{id})

List keywords

• Request
• Response
• Body
• Schema
• Model
• Header & Headers
• Parameter & Parameters
• Values
• Attribute & Attributes
• Relation

NOTE: Avoid using these keywords in other Markdown headers or lists

NOTE: With the exception of HTTP methods keywords the section keywordsare case insensitive.

Identifier

A section definition may or must include an identifier of the section.An identifier is any non-empty combination of any character except [, ],(, ) and newline characters.

An identifier must not contain any of the keywords.

Example

Description

A section description is any arbitrary Markdown-formatted content following thesection definition.

It is possible to use any Markdown header or list item in a section descriptionas long as it does not clash with any of thereserved keywords.

NOTE: It is considered good practice to keep the header level nestedunder the actual section.

Nested sections

A section may contain another nested section(s).

Depending on the nested section type, to nest a section simply increase itsheader level or its list item indentation. Anything between the section startand the start of following section at the same level is considered to be partof the section.

What sections can be nested and where depends upon the section in case, asdescribed in the relevant section's entry.

Example: Nested header-defined section

Example: Nested list-defined section

NOTE: While not necessary it is a good habit to increase the level of anested section markdown-header.

NOTE: A markdown-list section is always considered to be nested under thepreceding markdown-header section.

NOTE: Sections marked as 'Abstract' serve as a base for other sectionsand as such they cannot be used directly.

Named section

• Abstract
• Parent sections: vary, see descendants
• Nested sections: vary, see descendants
• Markdown entity: header, list
• Inherits from: none

Definition

Defined by a keyword followed by an optional section name -identifier in a Markdown header or list entity.

Description

Named section is the base section for most of the API Blueprint sections. Itconforms to the general section and as such it iscomposed of a section name (identifier), description and nested sections orspecific formatted content (see descendants descriptions).

Example

Asset section

• Abstract
• Parent sections: vary, see descendants
• Nested sections: none
• Markdown entity: list
• Inherits from: none

Definition

Defined by a keyword in Markdown list entity.

Description

The asset section is the base section for atomic data in API Blueprint. The contentof this section is expected to be apre-formatted code block.

Example

Example: Fenced code blocks

Payload section

• Abstract
• Parent sections: vary, see descendants
• Nested sections:0-1 Headers section, 0-1 Attributes section, 0-1 Body section, 0-1 Schema section
• Markdown entity: list
• Inherits from: Named section

Definition

Defined by a keyword in Markdown list entity. The keyword may be followed by identifier.The definition may include payload's media-type enclosed in braces.

NOTE: Refer to descendant for the particular section type definition.

Description

Payload sections represent the information transferred as a payload of an HTTPrequest or response messages. A Payload consists of optional meta informationin the form of HTTP headers and optional content in the form of an HTTP body.

Furthermore, in API Blueprint context, a payload includes its description,description of its message-body attributes and a message-body validationschema.

A payload may have its media type associated. A payload's media typerepresents the metadata received or sent in the form of a HTTP Content-Typeheader. When specified a payload should include nestedBody section.

This section should include at least one of the following nested sections:

If there is no nested section the content of the payload section is consideredas content of the Body section.

Relation of Body, Schema and Attributes sections

Each of body, schema and attributes sections describe a message payload's body.These descriptions should be consistent, not violating each other. Whenmultiple body descriptions are provided they should be prioritized asfollows:

1. For resolving message-body schema

   1. Schema section
   2. Attributes section
   3. Body section

2. For resolving message-body example

   1. Body section
   2. Attributes section
   3. Schema section

Referencing

Instead of providing a payload section content, amodel payload section can be referenced using theMarkdown implicit reference syntax:

Example

Example: Referencing model payload

Metadata section

• Parent sections: none
• Nested sections: none
• Markdown entity: special
• Inherits from: none

Definition

Key-value pairs. Each key is separated from its value by a colon (:). Onepair per line. Starts at the beginning of the document and ends with the firstMarkdown element that is not recognized as a key-value pair.

Description

Metadata keys and their values are tool-specific. Refer to relevant tooldocumentation for the list of supported keys.

Example

API name & overview section

• Parent sections: none
• Nested sections: none
• Markdown entity: special, header
• Inherits from: Named section

Definition

Defined by the first Markdown header in the blueprint document, unless itrepresents another section definition.

Description

Name and description of the API

Example

Resource group section

• Parent sections: none
• Nested sections:0+ Resource section
• Markdown entity: header
• Inherits from: Named section

Definition

Defined by the Group keyword followed by group name (identifier):

Description

This section represents a group of resources (Resource Sections). Mayinclude one or more nested Resource Sections.

Example

Resource section

• Parent sections: none, Resource group section
• Nested sections:0-1 Parameters section, 0-1 Attributes section, 0-1 Model section, 1+ Action section
• Markdown entity: header
• Inherits from: Named section

Definition

Defined by an URI template:

-- or --

Defined by a resource name (identifier) followed by anURI template enclosed in square brackets [].

-- or --

Defined by an HTTP request method followed by URI template:

-- or --

Defined by a resource name (identifier) followed by anHTTP request method and an URI template enclosedin square brackets []:

NOTE: In the latter two cases the rest of this section represents theAction section including its description and nestedsections and follows the rules of the Action section instead.

Description

An API resource as specified byits URI or a set of resources (a resource template) matching its URItemplate.

Vivavideo pro pc version. This section should include at least one nestedAction section and may include following nestedsections:

• URI parameters defined in the scope of a Resource section apply toany and all nested Action sections except when an URI template hasbeen defined for the Action.

• Attributes defined in the scope of a Resource section represent Resourceattributes. If the resource is defined with a name these attributes maybe referenced in Attributes sections.

• Additional Action sections

NOTE: A blueprint document may contain multiple sections for the sameresource (or resource set), as long as their HTTP methods differ. However itis considered good practice to group multiple HTTP methods under one resource(resource set).

Example

Resource model section

• Parent sections:Resource section
• Nested sections:Refer to payload section
• Markdown entity: list
• Inherits from: Payload section

Definition

Defined by the Model keyword followed by an optional media type:

Description

A resource manifestation - oneexemplary representation of the resource in the form of apayload.

Referencing

The payload defined in this section may be referenced in any response orrequest section in the document using parent section's identifier. You canrefer to this payload in any of the following Requestor Response payload sections using the Markdownimplicit reference syntax.

Example

Schema section

• Parent sections:Payload section
• Nested sections: none
• Markdown entity: list
• Inherits from: Asset section

Definition

Defined by the Schema keyword in Markdown list entity.

Description

Specifies a validation schema for the HTTP message-body of parent payload section.

Example

Following example uses Body section to provide an example of an application/json payload, and Schema section to provide a JSON Schema describing all possible valid shapes of the payload.

Action section

• Parent sections:Resource section
• Nested sections:0-1 Relation section,0-1 URI parameters section,0-1 Attributes section,0+ Request section,1+ Response section
• Markdown entity: header
• Inherits from: Named section

Definition

Defined by an HTTP request method:

-- or --

Defined by an action name (identifier) followed by anHTTP request method enclosed in square brackets [].

-- or --

Defined by an action name (identifier) followed by anHTTP request method andURI template enclosed in square brackets [].

Description

Definition of at least one complete HTTP transaction as performed with theparent resource section. An action section may consist of multiple HTTPtransaction examples for the given HTTP request method.

This section may include one nestedURI parameters section describing any URIparameters specific to the action – URI parameters discussed in the scope ofan Action section apply to the respective Action section ONLY.

This section may include one nested Attributes section defining theinput (request) attributes of the section. If present, these attributesshould be inherited in every Action's Request section unless specifiedotherwise.

Action section should include at least one nestedResponse section and may include additional nestedRequest and Response sections.

Nested Request and Response sections may be ordered into groups where eachgroup represents one transaction example. The first transaction example groupstarts with the first nested Request or Response section. Subsequent groupsstart with the first nested Request section following a Response section.

Multiple Request and Response nested sections within one transaction exampleshould have different identifiers.

Example

Example Multiple Transaction Examples

NOTE: The 'Multiple Transaction Examples' example demonstrates threetransaction examples for one given action:

Using Markdown In Html

1. 1st example: request A, response 200
2. 2nd example: request B, responses 200 and 500
3. 3rd example: requests C and D, response 200

Request section

• Parent sections:Action section
• Nested sections:Refer to payload section
• Markdown entity: list
• Inherits from: Payload section

Markdown Api Spec

Definition

Defined by the Request keyword followed by an optional identifier:

Description

One HTTP request-message example – payload.

Example

Response section

• Parent sections:Action section
• Nested sections:Refer to payload section
• Markdown entity: list
• Inherits from: Payload section

Definition

Defined by the Response keyword. The response section definition shouldinclude an HTTP status code as its identifier.

Description

One HTTP response-message example – payload.

Example

URI parameters section

• Parent Sections:Resource section | Action section
• Nested Sections: none
• Markdown entity: list
• Inherits from: none, special

Definition

Defined by the Parameters keyword written in a Markdown list item:

Description

Discussion of URI parameters in the scope of the parent section.

This section must be composed of nested list items only. This sectionmust not contain any other elements. Each list item describes a single URIparameter. The nested list items subsections inherit from theNamed section and are subject to additional formatting asfollows:

Where:

Markdown Api Template

• <parameter name> is the parameter name as written inResource Section's URI (e.g. 'id').
• <description> is any optional Markdown-formatted description of theparameter.
• <additional description> is any additional optional Markdown-formatteddescription of the parameter.
• <default value> is an optional default value of the parameter – a valuethat is used when no value is explicitly set (optional parameters only).
• <example value> is an optional example value of the parameter (e.g. 1234).
• <type> is the optional parameter type as expected by the API (e.g.'number', 'string', 'boolean'). 'string' is the default.
• Members is the optional enumeration of possible values.<type> should be surrounded by enum[] if this is present.For example, if enumeration values are present for a parameter whose type isnumber, then enum[number] should be used instead of number to.
• <enumeration value n> represents an element of enumeration type.
• required is the optional specifier of a required parameter(this is the default)
• optional is the optional specifier of an optional parameter.

NOTE: This section should only contain parameters that are specifiedin the parent's resource URI template, and does not have to list every URIparameter.

Example

Attributes Section

• Parent sections:Resource section | Action section | Payload section
• Nested sections: See Markdown Syntax for Object Notation
• Markdown entity: list
• Inherits from: none

Definition

Defined by the Attributes keyword followed by an optionalMSON Type Definition enclosed in parentheses.

<Type Definition> is the type definition of the data structure beingdescribed. If the <Type Definition> is not specified, an object base typeis assumed. See MSON Type Definition for details.

Example

Description

This section describes a data structure using theMarkdown Syntax for Object Notation (MSON).Based on the parent section, the data structure being described is one of thefollowing:

1. Resource data structure attributes (Resource section)
2. Action request attributes (Action section)
3. Payload message-body attributes (Payload section)

Data structures defined in this section may refer to any arbitrary datastructures defined in the Data Structures section aswell as to any data structures defined by a named resource attributesdescription (see below).

Resource Attributes description

Description of the resource data structure.

If defined in a named Resource section, this datastructure may be referenced by other data structures using the resourcename.

Example

NOTE: This data structure can be later referred as:

Action Attributes description

Description of the default request message-body data structure.

If defined, all the Request sections of the respectiveAction section inherits these attributes unlessspecified otherwise.

Example

Payload Attributes description

Description of payload (request, response, model) message-body attributes.

Not every attribute has to be described. However, when an attribute isdescribed, it should appear in the respectiveBody section example, if a Body section is provided.

If defined, the Body sectionmay be omitted and theexample representation should be generated from the attributes description.

The description of message-body attributes may be used to describemessage-body validation if no Schema section isprovided. When a Schema section is provided, the attributes descriptionshould conform to the schema.

Example

Headers section

• Parent sections:Payload section
• Nested sections: none
• Markdown entity: list
• Inherits from: none

Definition

Defined by the Headers keyword in Markdown list entity.

Description

Specifies the HTTP message-headers of the parent payload section. The contentthis section is expected to be a pre-formatted code blockwith the following syntax:

One HTTP header per line.

Example

Body section

• Parent sections:Payload section
• Nested sections: none
• Markdown entity: list
• Inherits from: Asset section

Definition

Defined by the Body keyword in Markdown list entity.

Description

Specifies the HTTP message-body of a payload section.

Example

Data Structures section

• Parent sections: none
• Nested sections:MSON Named Type definition (see below)
• Markdown entity: header
• Inherits from: none

Definition

Defined by the Data Structures keyword.

Description

This section holds arbitrary data structures definitions defined in the form ofMSON Named Types.

Data structures defined in this section may be used in any Attributes section.Similarly, any data structures defined in a Attributes section of a namedResource Sectionmay be used in a data structure definition.

Refer to the MSON specification for full details on how to define an MSON Named type.

Example

Example reusing Data Structure in Resource

Example reusing Resource-defined Data Structure

Relation section

• Parent sections:Action section
• Nested Sections: none
• Markdown entity: list
• Inherits from: none

Definition

Defined by the Relation keyword written in a Markdown list item followed by acolon (:) and a link relation identifier.

Description

This section specifies a link relation typefor the given action as specified by RFC 5988.

NOTE: The link relation identifiers should be unique per resource in the blueprint document.

Example

URI Templates

The API Blueprint uses a subset of RFC6570 to define a resource URI Template.

URI Path Segment

At its simplest form – without any variables – a path segment of anURI Template is identical to an URI path segment:

URI Template Variable

Variable names are case-sensitive. The variable name may consists of followingcharacters only:

• ASCII alpha numeric characters (a-z, A-Z)
• Decimal digits (0-9)
• _
• Percent-encoded characters
• .

Multiple variables are separated by the comma without any leading ortrailing spaces. A variable(s) must be enclosed in braces – {}without any additional leading or trailing whitespace.

Operators

The first variable in the braces might be preceded by an operator.API Blueprint currently supports the following operators:

• # – fragment identifier operator
• + – reserved value operator
• ? – form-style query operator
• & – form-style query continuation operator

Examples

NOTE: The explode variable modifier is also supported.Refer to RFC6570 for its description.

Variable Reserved Values

Following characters are reserved in variable values:

: / / / ? / # / [ / ] / @ / ! / $ / & / ' / ( / ) / * / + / , / ; / =

Path Segment Variable

Simple path segment component variable is defined without any operator:

With var := 42 the expansion is /path/to/resources/42.

NOTE: RFC6570 – Level 1

Fragment Identifier Variable

URI Template variables for fragment identifiers are defined using thecrosshatch (#) operator:

With var := my_id the expansion is /path/to/resources/42#my_id.

NOTE: RFC6570 – Level 2

Variable with Reserved Characters Values

To define URI Template variables with reserved URI characters,use the plus (+) operator:

With var := to/resources the expansion is /path/to/resources/42. The first templar game free download.

NOTE: RFC6570 – Level 2

Form-style Query Variable

To define variables for a form-style query use the question mark (?) operator

With varone := 42 and vartwo = hello the expansion is /path/to/resources/42?vartwo=hello.

To continue a form-style query use the ampersand (&) operator:

With varone := 42, vartwo = hello, varthree = 1024 the expansion is /path/to/resources/42?path=test&vartwo=hello&varthree=1024.

NOTE: RFC6570 – Part of Level 3