API Ary - Draft

apiary.txt

[#ftl]
[#-- @ftlvariable name="resourceApis" type="java.util.List<com.webcohesion.enunciate.api.resources.ResourceApi>" --]
[#-- @ftlvariable name="serviceApis" type="java.util.List<com.webcohesion.enunciate.api.services.ServiceApi>" --]
[#-- @ftlvariable name="data" type="java.util.List<com.webcohesion.enunciate.api.datatype.Syntax>" --]
[#-- @ftlvariable name="title" type="java.lang.String" --]
[#-- @ftlvariable name="disableMountpoint" type="java.lang.Boolean" --]
[#-- @ftlvariable name="disableResourceLinks" type="java.lang.Boolean" --]
[#-- @ftlvariable name="apiRelativePath" type="java.lang.String" --]
[#-- @ftlvariable name="includeApplicationPath" type="java.lang.Boolean" --]

[#function extract_headers method]
    [#local result = []]
    [#if method.parameters?size > 0]
        [#list method.parameters as thing]
            [#if thing["typeLabel"] == "header"]
                [#local result = result + [thing]]
            [/#if]
        [/#list]
    [/#if]
    [#return result]
[/#function]

[#function extract_query_params method]
    [#local result = []]
    [#if method.parameters?size > 0]
        [#list method.parameters as thing]
            [#if thing["typeLabel"] == "query"]
                [#local result = result + [thing]]
            [/#if]
        [/#list]
    [/#if]
    [#return result]
[/#function]

[#function extract_path_params method]
    [#local result = []]
    [#if method.parameters?size > 0]
        [#list method.parameters as thing]
            [#if thing["typeLabel"] == "path"]
                [#local result = result + [thing]]
            [/#if]
        [/#list]
    [/#if]
    [#return result]
[/#function]

[#function check_for_parameters method]
    [#if method.parameters?size > 0]
        [#list method.parameters as thing]
            [#if thing["typeLabel"] == "path"]
                [#return true]
            [/#if]
            [#if thing["typeLabel"] == "query"]
                [#return true]
            [/#if]
        [/#list]
    [/#if]
    [#return false]
[/#function]

[#function apiary_type n]
    [#if n.label??]
        [#if n.label == "int"]
            [#return "number"]
        [/#if]
        [#if n.label == "long"]
            [#return "number"]
        [/#if]
        [#if n.label == "double"]
            [#return "number"]
        [/#if]
        [#if n.label == "float"]
            [#return "number"]
        [/#if]
        [#if n.label == "anyType"]
            [#return "object"]
        [/#if]  
        [#if n.label == "dateTime"]
            [#return "string"]
        [/#if]            
        
        [#return (n.label!"string")]
    [#else]
        [#return "string"]
    [/#if]
[/#function]

[@file name="apiary.adoc"]

[#list resourceApis as resourceApi]
[#list resourceApi.resourceGroups as resourceGroup]

[@file name=resourceGroup.slug + ".html"]
FORMAT: 1A
HOST: http://polls.apiblueprint.org/

[#assign item = resourceGroup.resources[0]]
# API Documentation

This document outlines how to interact with Catalina core services to allow third parties 
and other applications the ability to dynamically drive consumer journies and direct marketing
activities using our world-class consumer purchase database powered by worldwide storefronts.

## Security

You must be granted a security token in order to access this API, where you will be given an
account token that will enable your access to data and filter requests and responses from the
system to ensure the right data is delivered to you at just the right volume and permissions.

Please contact promotastic@catalina.com for access tokens. Once you have your access tokens
you can login using our security JWT server at https://partner.api.catalina.com/security.

[#assign item = resourceGroup.resources[0]]
## ${resourceGroup.label} [${item.path}]

[#if resourceGroup.description??]${resourceGroup.description}[/#if]
[#list resourceGroup.resources as resource][#if resource.version??]Version: ${resource.version},[/#if] [#if resource.since??]Since: ${resource.since}[/#if]
[#list resource.methods as method]

### ${resource.path} [${method.label} ${resource.path}] [#assign has_url_parameters = check_for_parameters(method)]

${method.description}

[#if has_url_parameters]
+ Parameters 
[#assign paths = extract_path_params(method)]
[#assign qs = extract_query_params(method)]
[#list paths as parameter]
    + ${(parameter.name)!"N/A"}:[#if parameter.defaultValue??] `${parameter.defaultValue}` [/#if](${(parameter.constraints)!"string"}) - ${(parameter.description)!"N/A"} ... ${(parameter.typeLabel)!""} ${(parameter.dataType)!""}
[/#list]
[#list qs as parameter]
    + ${(parameter.name)!"N/A"}:[#if parameter.defaultValue??] `${parameter.defaultValue}` [/#if](${(parameter.constraints)!"string"}) - ${(parameter.description)!"N/A"} ... ${(parameter.typeLabel)!""} ${(parameter.dataType)!""}
[/#list][/#if]

+ Request (application/json)
[#assign headers = extract_headers(method)]
[#if headers?size > 0]

    + Headers
    
    [#list headers as header]
            ${header.name}: ${header.description!"N/A"}
    [/#list][/#if]
[#if method.requestEntity??][#list method.requestEntity.mediaTypes as io][#if io.syntax??][#if io.syntax == "JSON"]

    + Attributes (${(io.dataType.label)!"N/A"})    
[/#if][/#if][/#list][/#if]
    
+ Response 200 (application/json)

[#if method.responseEntity??]
    [#list method.responseEntity.mediaTypes as io]
    + Attributes (${(io.dataType.label)!"string"})    
    [/#list]
[/#if]

[#if method.responseHeaders?size > 0]
    + Headers
    [#list method.responseHeaders as header]
            ${header.name}: ${header.description!"N/A"}
    [/#list][/#if]

[/#list]

[/#list]

# Data Structures

[#if data?size > 0]
[#list data as syntax]
[#list syntax.namespaces as ns]
[#list ns.types as type]
## ${type.label} [#if type.supertypes??](${apiary_type(type.supertypes[0])})[#else][#if type.values??](enum[string])[#else](object)[/#if][/#if] [#if type.subtypes??]

This object has subtypes [#list type.subtypes as subtype]${apiary_type(subtype)}, [/#list] browse to see more.[/#if]

[#if type.properties??]
### Properties

[#list type.properties as property]
- `${property.name}` (${ apiary_type(property.dataType) }) - ${(property.description!"No description provided")?replace("(\r\n)+", " ",'r')?replace('<[^>]+>','','r') }
[/#list][/#if][#if type.values??][#list type.values as value]
- `${value.value}` - ${ (value.description!"(no description provided)")?replace("(\r\n)+", " ",'r')?replace('<[^>]+>','','r') }
[/#list][/#if][#if type.supertypes??][#list type.supertypes as supertype][#if supertype.value?? && supertype.value.properties?? && supertype.value.properties?size > 0][#list supertype.value.properties as superProperty]
- `${superProperty.name}` (${ apiary_type(superProperty.dataType) }) - ${(superProperty.description!"No description provided")?replace("(\r\n)+", " ",'r')?replace('<[^>]+>','','r') }
[/#list][/#if][/#list][/#if]

[/#list]
[/#list]
[/#list]
[/#if]
    

[/@file]

[/#list]
[/#list]
[/@file]