Endpoint has different types of responses


#1

Hello,

When I GET an endPoint with a query parameter ‘id’, specifying a valid value, the response is an object. If no parameter ‘id’ is provided the response is an array oif objects. In both cases the objects have an identical schema (i.e. properties). In my Raml definition file I want to provide examples for the get section of this endpoint. I can povide just one responseType - and so one of the examples results in an syntax error. How canI specify that a GET can result in either an response that contains an array or an object?

I use the Api Workbench of Atom to define the Api.

get:
    queryParameters:
      jobDomainId:
        required: false
    responses:
      200:
        body:
          application/json:
            type: array #-- not specifying type of response since it varies: no teamId gives array, specifying teamId gives object
            facets: 
              objects:
                properties:
                  parent: string
                  displayName: string
                  id: string
                  companyCultureId: string
                  matchingId: string
                  domainOwnerId: string
            examples:
              array:
               # here I define an array
              singleton:
               # here I define an object. It gives me a syntax error

#2

Why are you trying to consolidate that into a single resource? Usually you would have something like that:

/books
  get:
/books/{id}
  get:

#3

Ah…of course, that makes sense. Refactoring the .raml file. Thanks!


#4

On 2nd thought…

/books/{id} is like /books/233 right? We use queryparameters so that would be book/?id=233 (or /book?id=233). Will that also work with /books/{id}?

Marc


#5

Its exactly the same, but you use URI parameters (/{id}) instead of query parameters (?id=). Using URI parameters in your case fits a bit better to the resource-based API approach.


#6

Ah… I know the queryparams are functionally identical to to uriparams but since that is extra work I’d prefer not to change them in the backend.
So an Api call like /?id=233 cannot be described as in the snippet below? Looks to me that translates to an uri like /person/231/?personId=231? and not /person?personId=231.

  /{personId}:
    get:
      queryParameters:
        personId:
          required: true
          type: string
      responses: 
        200:
          body: 
            application/json:
              example:
                 .....

Thanks for the reply.


#7

You would not define /{personId} with queryParameters. It would be a uriParameter. Query parameters would be part of the URI when called, but not part of the resource URI line… only defined in the queryParameters section, as you have in the snippet. Just remove the /{personId} part off of the URI line.


#8

If you want to have an url like : - /person?personId=231 then, following will be applied : -
/person:
get:
queryParameters:
personId:
required: true
type: string
responses:
200:
body:
application/json:

and not /{personId}: as it will create uriParameter