Type definition approach

Question

Suppose that I have a endpoint that support three methods: GET, POST and PUT.

The type that will be returned contais two attributes: an id and a name. Both are required.

My question is about how to define this type in RAML definition, since on POST, the id should be crated automatically and on PUT the id will be a URI parameter. Do you guys creates two Types (one for GET and other for PUT, POST) or uses the same type for all operations, declaring the id as not required?

Sorry if this appears to be a such basic question, but I searched for this and didn't get any conclusive responses.

Thanks a lot!

Answer 1

Perhaps you can provide an example of how you expect it to work. Also please specify the RAML version you are using (assuming 1.0 for now).

Your endpoint provides a POST. That implies some kind of collection that you can add an item to. Then you can use the GET to retrieve such an item.

• you can create a second endpoint for an item of your collection: you'll end up with a /collection (all items) and a /collection/12345678 (one item alone, specifically, the item with id 12345678)
• or you can use the query string to filter your collection to find that specific item: /collection?id=12345678 (a subset of the collection that happens to contain one item instead of multiple)

Maybe, you could also look into the use of uriParameters.

To illustrate:

/types:
    myidtype:
        type: string
        pattern: ^[0-9]{8}$
/collection:
    get: # to retrieve the entire collection
        queryParameters: # to be able to filter the collection into a subset of 1 or more items
            id:
                type: myidtype
                required: false
            name:
                type: string
                required: false
    post: # to create a new item and add it to the collection, id and name will go in the body
    /{myId}: # this is one item
        uriParameters:
            myId:
                type: myidtype
        get: # to retrieve all information on this item
        post: # to post some property to this item

Please note that my example is not completely correct. It's about the concept rather than the precise syntax.