Describing URI parameters in RAML

api rest raml
Xtreme Biker picture Xtreme Biker · Sep 23, 2014 · Viewed 14.4k times · Source

I'm declaring a REST service API stub in RAML. My web application provides equipment, which can be listed, obtained by id or by code. When I want the whole list, I don't specify any URI parameter, however, to get a concrete equipment, I do. That's its current state:

/equipment:
    get:
      body:
        application/json:
        application/xml:
    description:
      List all the equipment
    /id/{equipmentId}:
      get:
         body:
          application/json:
          application/xml:
      description:
        Get an equipment by id 
    /code/{code}:
        get:
          body:
            application/json:
            application/xml:
        description: 
              Get an equipment by code

Here, in description fields I write what the current call performs. However, I would like to add a description for the parameter passed in the URI itself (id or code). Is there a way to achieve it?

Answer

David Dossot picture David Dossot · Sep 24, 2014

You are missing uriParameters sections to describe the equipmentId and code parameters. In such section, you can specify the usual: type, description...

See section Template URIs and URI Parameters in the spec: https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md#template-uris-and-uri-parameters

Related questions

How do I make calls to a REST API using C#?

This is the code I have so far: using System; using System.Collections.Generic; using System.Linq; using System.Text; using System; using System.Net.Http; using System.Web; using System.Net; using System.IO; namespace ConsoleProgram { public class Class1 { …

Read More
How do you set the Content-Type header for an HttpClient request?

I'm trying to set the Content-Type header of an HttpClient object as required by an API I am calling. I tried setting the Content-Type like below: using (var httpClient = new HttpClient()) { httpClient.BaseAddress = new Uri("http://example.com/"); httpClient.DefaultRequestHeaders.…

Read More
REST API Best practices: Where to put parameters?

A REST API can have parameters in at least two ways: As part of the URL-path (i.e. /api/resource/parametervalue ) As a query argument (i.e. /api/resource?parameter=value ) What is the best practice here? Are there any …

Read More