Skip to content

Home

Jump to bottom
SRV edited this page Feb 5, 2018 · 10 revisions

Getting Started

This section will show step-by-step guide on how expose two command-line programs as single REST service. This service will provide information about memory on target machine and converts HTML into PDF.

Initial setup:

  • Linux-based OS. Note that go2rest may run on every platform supported by Go compiler so OS limitation introduced just for this example.
  • Build go2rest using go build
  • Install pandoc command-line program
  • Ensure that you have free command-line program as a part of your distribution

Write RAML file

The first step is to describe shape of your REST API using RAML 1.0 markup language with some extensions required by go2rest.

You can use the following template as starting point for API description:

#%RAML 1.0
title: Service Name
version: v1
baseUri: http://url.to.your.api
annotationTypes:
  exitCode: integer
  commandPattern: string

go2rest extends RAML-based description of API using annotations described in annotationTypes section. This is mandatory section for every description of API consumes by go2rest. Annotations is a standard way to provide extensions to RAML markup according with RAML Specificiation. Therefore, RAML documentation generator correctly understands these annotations. Let's take a look at these annotations:

  • commandPattern describes text template used to define command-line program to execute and its arguments. Some of arguments can be replaced with placeholder which actual value will be extracted from HTTP request and placed into command
  • exitCode required for mapping between process exit code and HTTP status code. This help to obtain correct status code in HTTP response according with exit code of process. All data in stderr will be included into HTTP response.

Let's take a look at the following example:

#%RAML 1.0
title: New Microservice
version: v1
baseUri: http://localhost
annotationTypes:
  exitCode: integer
  commandPattern: string
/memory:
  get:
    queryParameters:
      uom:
        type: string
        required: false
        default: m
        enum: [m, k, g]
        description: | 
          Unit of measurement. Possible values: m (megabytes), k (kilobytes), g (gigabytes)
    (commandPattern): free -{{.uom}}
    responses:
      200:
        description: OK
        (exitCode): 0
        body:
          text/plain:
            type: string
      400:
        description: Bad request
        (exitCode): 1
        body:
          text/plain:
            type: string
/convert/md-to-html:
  post:
    (commandPattern): pandoc -f markdown_github -t html --html-q-tags {{.body}}
    body:
      text/markdown:
        type: file
    responses:
      200:
        description: OK
        (exitCode): 0
        body:
          text/html:
            type: file

Endpoint /memory allows to obtain memory status produced by free command-line program. This description consists of the following important parts:

  • get section means that data can be requested using GET HTTP request. Single endpoint may provide one or more different HTTP methods: PUT, POST, DELETE, PATCH etc.
  • queryParameters describes set of supported query parameters. Parameter uom is optional and has type string. This parameter may accept one of three possible values as described in enum section
  • (command-pattern) is go2rest-specific annotation describes program name and its parameters. Actual argument of parameters will be extracted from HTTP request and placed into this template instead of placeholders. Name of parameter inside of placeholder (in our example it is {{.uom}}) matches to query parameter.
  • responses section describes possible HTTP responses. Each response code contains mapping with program exit code defined with (exitCode).

Endpoint convert/md-to-html allows to convert Markdown document passed in HTTP request into HTML document returned in HTTP response. Special type file can be used to save content of request into temporary file. Actual value of the file-typed argument contains full path to the temporary file with request content, not the content itself. body parameter defined in template is a reserved name that contains HTTP request body. In this case, body parameter points to temporary file name because body type is file. If you define body type as integer or string then it will contain entire HTTP request of this type.

go2rest supports definition of the following parts of API:

  • queryParameters defines a set of query parameters and should be placed inside of HTTP method definition
  • uriParameters defines a set of path parameters and should be placed outside of HTTP method definition
  • headers defines a set of headers and should be placed inside of HTTP method definition

Command pattern

Command pattern should be described using Go Template syntax. The name of parameter should match to one of named parameter specified in queryParameters, uriParameters or headers section. Parameter with name body reserved for HTTP request body content.

Exit code

If RAML model doesn't provide appropriate exit code mapping then go2rest responds with 500 Internal Server Error and stderr of process will be returned in HTTP response.

Running REST service

Save the model described above into file example.raml and run program as go2rest -port 3535 ./example.raml. Now memory status can be obtained in the following way:

 wget -qO- http://localhost:3535/memory

For convert/md-to-html you can use any valid Markdown document. Let's take README.md file from this repository:

wget -qO - -S --header="Content-Type: text/markdown" --post-file ./README.md http://localhost:3535/convert/md-to-html
Clone this wiki locally