21 App Manifest Walkthrough

Posted by John Granata, Michael Goldstein

21 App Manifest Walkthrough

Introduction

Each bitcoin app indexed on the 21 Marketplace is described by a manifest, which is a YAML file that extends a Swagger REST API definition. The full Swagger specification is available here. The manifest is a specification for your bitcoin app that provides information used for indexing your app, and for providing potential customers with usage details. The file should not be larger than 2MB.

Manifests can be edited manually in a text editor, or you can open the template in the swagger editor.

You can test if your specification is valid Swagger anytime by visiting the following URL (replace YOUR_URL with the url of your manifest.yaml:

http://online.swagger.io/validator/?url={YOUR_URL}

Example Manifest

Below is an example manifest from the Sentiment Analysis app in the 21 Marketplace:

basePath: /text_sentiment
definitions:
  InvalidInput:
    properties:
      error:
        type: string
    type: object
  ProcessingError:
    properties:
      error:
        type: string
    type: object
  SentimentResponse:
    properties:
      mixed:
        type: string
      score:
        type: string
      type:
        type: string
    required:
    - type
    - score
    type: object
host: apps.21.co
info:
  contact:
    email: support@21.co
    name: 21.co
    url: https://21.co
  description: Analyze text, URLs, or HTML for sentiment.
  license:
    name: MIT LICENSE
    url: https://opensource.org/licenses/MIT
  termsOfService: https://opensource.org/licenses/MIT
  title: Textual Sentiment Analysis
  version: '0.1'
  x-21-app-image: https://cdn.filepicker.io/api/file/w3zvpSaUTPeg38TFdR0n
  x-21-category: Utilities
  x-21-github-profile-url: ''
  x-21-github-project-url: ''
  x-21-keywords:
  - nlp
  - text analysis
  - sentiment
  x-21-quick-buy: '$ 21 buy "21dotco/textual_sentiment_analysis/text_sentiment/text"
    --data ''{"text": "On balance, overall employment has continued to grow at a solid
    pace so far this year, in part because domestic household spending has been sufficiently
    strong to offset the drag coming from abroad. Looking forward however, we have
    to take into account the potential fallout from recent global economic and financial
    developments, which have been marked by bouts of turbulence since the turn of
    the year."}'' --maxprice 5000


    # Output:

    # {

    #   "docSentiment":{

    #     "type":"positive",

    #     "mixed":"1",

    #     "score":"0.0451983"

    #   }

    # }


    $ 21 buy "21dotco/textual_sentiment_analysis/text_sentiment/url" --data ''{"url":
    "medium.com/@21/a-bitcoin-miner-in-every-device-and-in-every-hand-e315b40f2821"}''
    --maxprice 5000


    # Output:

    # {

    #   "docSentiment":{

    #     "type":"positive",

    #     "mixed":"1",

    #     "score":"0.429642"

    #   }

    # }


    $ 21 buy "21dotco/textual_sentiment_analysis/text_sentiment/html" --data ''{"html":
    "<html><body>I bought Bitcoin!</body></html>"}'' --maxprice 5000


    # Output:

    # {

    #   "docSentiment":{

    #     "score":"0.231787",

    #     "type":"positive"

    #   }

    # }

    '
  x-21-total-price:
    max: 3500
    min: 3500
parameters:
  htmlParam:
    description: html
    in: body
    name: html
    required: true
    schema:
      properties:
        html:
          type: string
  textParam:
    description: text
    in: body
    name: text
    required: true
    schema:
      properties:
        text:
          type: string
  urlParam:
    description: url
    in: body
    name: url
    required: true
    schema:
      properties:
        url:
          type: string
paths:
  /html:
    post:
      consumes:
      - application/json
      parameters:
      - $ref: '#/parameters/htmlParam'
      produces:
      - application/json
      responses:
        '200':
          description: Sentiment
          schema:
            $ref: '#/definitions/SentimentResponse'
        '400':
          description: Invalid input.
          schema:
            $ref: '#/definitions/InvalidInput'
        '500':
          description: Error processing request.
          schema:
            $ref: '#/definitions/ProcessingError'
      summary: Analyze sentiment of HTML
  /text:
    post:
      consumes:
      - application/json
      parameters:
      - $ref: '#/parameters/textParam'
      produces:
      - application/json
      responses:
        '200':
          description: Sentiment
          schema:
            $ref: '#/definitions/SentimentResponse'
        '400':
          description: Invalid input.
          schema:
            $ref: '#/definitions/InvalidInput'
        '500':
          description: Error processing request.
          schema:
            $ref: '#/definitions/ProcessingError'
      summary: Analyze sentiment of text
  /url:
    post:
      consumes:
      - application/json
      parameters:
      - $ref: '#/parameters/urlParam'
      produces:
      - application/json
      responses:
        '200':
          description: Sentiment
          schema:
            $ref: '#/definitions/SentimentResponse'
        '400':
          description: Invalid input.
          schema:
            $ref: '#/definitions/InvalidInput'
        '500':
          description: Error processing request.
          schema:
            $ref: '#/definitions/ProcessingError'
      summary: Analyze sentiment of URL
schemes:
- https
swagger: '2.0'
x-21-healthcheck-path: /healthcheck

Specification Field Guide - General Information

The first sections of the manifests include information about the app in general.

Optional field = *

Field Description
swagger The Swagger version. The 21 Marketplace uses '2.0'.
x-21-github-profile-url* The URL of your Github profile.
x-21-github-project-url* The URL of your app's Github project.
title The title of your app. Must be fewer than 30 characters.
description Short description of your app. Must be fewer than 50 characters.
termsOfService The Terms of Service for the API.
x-21-usage A description of the intended usage of the app. This description can be verbose and is displayed in the app detail view. Supports GitHub flavored markdown.
x-21-quick-buy A quick usage example that a user can copy and paste into the command line to make a simple purchase. This is displayed in the app preview when a listing is selected in the Marketplace.
x-21-category The category for your app. Choose (1) from: blockchain, entertainment, social, iot, utilities, or markets.
x-21-app-image* The image displayed next to your app listing. Upload your image here and paste the generated URL in this field. Images from other sources won't be displayed.
x-21-total-price List the minimum and maximum price for endpoints in your app. If there is a single endpoint with only one price, make the minimum and maximum equal.
name The author name to display with the published listing.
email The email associated with the published listing.
url The URL associated with the app's author.
host The host from which the app is being served. This can be a domain name or IP:PORT.
schemes The URI scheme for accessing your web service (i.e. http or https).
basePath The root path that is prepended to all other paths. For example, if the basePath is specified as /api, then a path designated as /test in the manifest will render as /api/test in your app description. Ensure there is no trailing / in the basePath field.

Specification Field Guide - Paths

An optional paths field allows you to specify information about the app's endpoints and specifies the type of data it consumes and produces. Below is a table describing each of the fields as they appear in the example. Your app may have different names and specifications.

Optional field = *
App-specific name = †
App-specific field = ‡

Field Description
/analyze The path object is the name of a relative path to an individual endpoint. It can use path templating to define path parameters with curly braces ({}).
post The operation object that describes a specific operation available on that path (e.g. GET, POST, DELETE, etc.).
parameters The parameter object describes the parameters that are passed into the request. These can be in the form of path, query, header, body, and form parameters. consumes and produces are optional fields that describe the MIME types of data in the request and response.
in This field specifies where in the request the parameter can be found. In this case, the body. See parameter object for more information.
schema The schema object specifies the object posted in the body. It can be a JSON object or a primitive object like an array or string. An object will have properties with a name (e.g. text) and a similar schema structure of its own. See parameter object to learn more about how to adapt this for your app.
$ref* This app does not use an optional reference object that allows an object to be defined in a Swagger definition at the end of the manifest so it does not have to be defined multiple times. This object is useful for maintaining a DRY principle, or if, for instance, an object is an array of an undefined amount of another object.
200* The responses object defines what the response is for a specific status code. It includes a response object that gives a description of the response and defines a schema object for the response (see above). The status code specifically is optional, but a responses object is not.

With these building blocks, plus the rest of the Swagger specification, you can construct detailed API specifications that help users all over the world interact with your bitcoin app.

Publish your app to the 21 Marketplace

If your app and manifest are ready to go, you can add a manifest endpoint and an optional client download endpoint and publish your app to the 21 Marketplace so that you can start earning bitcoin for digital services today. Learn how by reading the Publish an App to the 21 Marketplace tutorial.