HTTP POST parameter


#1

Hello! I’m new to RAML and already have a little problem.
The thing is I have an API that only gets an information about order by it’s ID. API passes parameters via HTTP GET (access_token) and POST (id) methods but when I describe parameters like this

/api/1c/v1/order:
  displayName: Order
  description: Get order's information
  get:
    queryParameters:
      access_token:
        description: Access token for API
        required: true
      id:
        description: Order's id
        required: true

both of them are passing via GET (request URL looks like this: <MY_BASE_URI>/api/1c/v1/order?access_token=<ACCESS_TOKEN>&id=<ORDER_ID>). And I need id parameter to be sent via POST. Can anybody help me to describe that POST parameter please?


#2

Hi everyone again! So it seems that it was a little misunderstood. I should carefully read documentation :slightly_smiling:
This is how it works (maybe it will be helpful for somebody):

/api/1c/v1/order:
  displayName: Order
  description: Get order's information
  post:
    queryParameters:
      access_token:
        description: Access token for API
        required: true
    body:
      application/x-www-form-urlencoded:
        formParameters:
          id:
            description: Order's id
            required: true

This way query parameter access_token sends via GET and id parameter sends in request body.


#3

Hi,

You can specify GET, POST, PUT, DELETE, PATCH all under each resource.

A couple of recommendations/thoughts on your URL and ID. First, not that it is wrong to do so, but using versions in the URL is typically the less preferred way to handle versioning. There are many reasons for and against both methods, just wanted to point that out in case you were not aware. A more common way to handle versioning is at the resource level using the media type header. E.g. Content-Type: application/json;version=1 or Content-Type: application/vnd.namespace-v1+json This approach allows you to version each resource instead of the entire API surface (e.g. all resources under it).

As for the ID, again, you are not doing anything wrong, but when you refer to a resource, typically the REST way is to use a sort of collections/item approach, where by the resource is a noun, and the collection is a plural. That would typically be how you POST (create) a new item (entity) to the collection. To update a single item, or get info of a single item, the URL is typically (in your example) /api/1c/v1/orders/{id} and in your definition, you describe the path param id with a description and type (string, etc).

If you are stuck using an already existing API and trying to describe it in RAML… well, that is most unfortunate. :D. I will add though that when you do a POST with query parameters, they are added to the body anyway as part of the POST request.