POST parameters support in RAML

Question

I'd like to ask if there is any support for POST parameters in RAML. And if there is - what is the syntax. I've browsed spec 0.8 and spec 1.0 roughly (actually I'm bound to 0.8, since many tools don't support 1.0 yet). I didn't find POST parameters support, but maybe I just missed something.

So what do I mean by POST parameters? These can be either of the two (sorry, I don't know their formal names, if there are any):

• HTTP plain parameters, key=value, each parameter in one line, such as

  name=John Doe amount=5 which is not really handy (e.g. no nesting)

• parameters as JSON object, just a JSON with all its syntax allowed (server-side needs to parse this json); such as:

  {"name":"John Doe","amount":"5"}

Different server-side API implementations use either 1st or 2nd one. Anyway, how does RAML support these?

Mcdougald

What content-type is being used for option 1? – Lenticularis

@DavidDossot It doens't matter, I can adjust it later on. The question is about the concept. You can assume that name is of type string and amount of type number. – Mcdougald

It matters because the content-type is part of the request body specification in RAML. Also I'm unfamiliar with this encoding and so I was hoping to learn more about it once I knew the type. – Lenticularis

For option 2, it's easy as @Pedro shown below. For option 1, the problem is to find a schema language that can describe a multi-line property-like document with types. – Lenticularis

@DavidDossot option one is in fact the default HTTP POST parameters handling. JSON (option 2) is its derivative... – Mcdougald

Answer 1

@Pedro has covered option 2, so here is option 1. Based on the discussion in the comments, it seems the encoding used is application/x-www-form-urlencoded.

You need to use formParameters.

Example:

  post:
    description: The POST operation adds an object to a specified bucket using HTML forms.
    body:
      application/x-www-form-urlencoded:
        formParameters:
          AWSAccessKeyId:
            description: The AWS Access Key ID of the owner of the bucket who grants an Anonymous user access for a request that satisfies the set of constraints in the Policy.
            type: string
          acl:
            description: Specifies an Amazon S3 access control list. If an invalid access control list is specified, an error is generated.
            type: string

Reference: https://github.com/raml-org/raml-spec/blob/master/raml-0.8.md#web-forms

Lenticularis

Answer 2

As it is shown in this reference https://github.com/raml-org/raml-spec/wiki/Breaking-Changes:

For raml 0.8:

body:
  application/x-www-form-urlencoded:
    formParameters:
      name:
        description: name on account
        type: string
        example: Naruto Uzumaki
      gender:
        enum: ["male", "female"]

Is the equivalent in raml 1.0 to:

body:
  application/x-www-form-urlencoded:
    properties:
      name:
        description: name on account
        type: string
        example: Naruto Uzumaki
      gender:
        enum: ["male", "female"]

So what it changes is the formParameters attribute to the properties one.

Viddah

Answer 3

Post parameters can be expressed using JSON Schema

A simple RAML 0.8 example:

#%RAML 0.8
title: Api
baseUri: /
schemas:
  - Invoice: |
    { 
      "$schema": "http://json-schema.org/draft-03/schema",
      "type": "object",
      "properties": {
        "Id": { "type": "integer"},
        "Name": { "type": "string"},
        "Total": { "type": "number"}
      }
    }
/invoices:
  post:
    body:
      application/json:
        schema: Invoice

Mclendon

so JSON schema might be used for both request schema and response schema definition, right? – Mcdougald

yes it can, see: github.com/raml-org/raml-spec/blob/master/raml-0.8.md#responses – Lenticularis

thank you both, gentleman. Sorry I can't accept both, I accept @DavidDossot as it seems the more difficult one. – Mcdougald