Geek Answers Handbook

RAML: how to require parameter A OR parameter B

I am writing some REST documentation with RAML, but I'm stuck.

My problem: - I have a GET request used to search, which can take the parameter "id" or ( exclusive or ) "link". only one of them is required .

I know how to say "this parameter is necessary," but I do not know how to say "one of these parameters is required." Is it possible?

+4
source share
3 answers

The following example, written in RAML 1.0, defines two types of objects in Urland File, then creates another object Itemthat requires UrlOR Filein ext. If you change the attached examples (which are currently being tested), you will see that they fail if the property does not match one or the other definition. Hope this helps! LMK, if you have other questions, and I will do my best.

[EDIT: hmm I think I see your problem now, the last example I just added, with a name should_fail(which has one of each type together in the example) still checks, and you want to make it a failure.]

[: . . maxProperties: 1 , , . , .]

#%RAML 1.0
types:
    Url:
        properties:
            url:
                type: string
                example: http://www.cats.com/kittens.jpg
                description: |
                    The url to ingest.

    File:
        properties:
            filename:
                type: string
                example: kittens.jpg
                description: |
                    Name of the file that will be uploaded.


    Item:
        description: |
            An example of a allowing multiple types yet requiring 
            one AND ONLY one of two possible types using RAML 1.0
        properties:
            ext: 
                maxProperties: 1
                type: File | Url
        examples:
            file_example:
                content:
                    ext:
                        filename: video.mp4
            url_example:
                content:
                    ext:
                        url: http://heres.a.url.com/asset.jpg
            should_fail:
                content:
                    ext:
                        url: http://heres.a.url.com/asset.jpg
                        filename: video.mp4
+1

. , , .

. [ ], FileInput. [ ], TextInput. .

union. . CatAndDog Raml 200 . .

types:
  FileInput:
    properties:
      parameters:
        type: Parameters
        description: (...)
      files:
        type: ArchiveCollection | FileCollection
        description: (...)


  TextInput:
    properties:
      parameters:
        type: Parameters
        description: (...)

      texts:
        type: TextCollection
        description: (...)

POST:

/your_route:
  post:
    body:
      multipart/form-data:
        type: TextInput | FileInput

TextInput FileInput.

+1

RAML 0.8 queryParameters .

In RAML 1.0 you can do this. You should use oneOf in jsonschema to describe Type. Your queryParametersshould use this type. Example:

api.raml

#%RAML 1.0
title: AUTH microservice
mediaType: application/json
protocols: [HTTPS]
types:
  - example: !include schemas/example.json
/example:
  get:
    queryParameters:
      type: example

Schemas /example.json

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "id": "file://schemas/credentials.json",
  "oneOf": [
    {
      "properties": {"key1": {"type": "string"}},
      "additionalProperties": false
    },
    {
      "properties": {"key2": {"type": "string"}},
      "additionalProperties": false
    }
  ]
}

Also you can use uriParameters. Perhaps this will help in your case.

#%RAML 0.8
title: API Using media type in the URL
version: v1
/users{mediaTypeExtension}:
  uriParameters:
    mediaTypeExtension:
      enum: [ .json, .xml ]
      description: Use .json to specify application/json or .xml to specify text/xml
0
source

More articles:


All Articles