Contact Free trial Login

Create a RAML Specification Using a Plain Text Editor

This task shows you how to create a sample RAML specification using a plain text editor:

  1. Create a JSON file that includes a list of users the API retrieves:

    [{
      "id": 1,
      "name": "Leanne Graham",
      "username": "Bret",
      "email": "Sincere@april.biz",
      "address": {
        "street": "Kulas Light",
        "suite": "Apt. 556",
        "city": "Gwenborough",
        "zipcode": "92998-3874",
        "geo": {
          "lat": "-37.3159",
          "lng": "81.1496"
        }
        },
      "phone": "1-770-736-8031 x56442",
      "website": "hildegard.org",
      "company": {
        "name": "Romaguera-Crona",
        "catchPhrase": "Multi-layered client-server neural-net",
        "bs": "harness real-time e-markets"
      } }]
  2. Save it as user-example.json

  3. Create a new blank file with the API specification:

    #%RAML 1.0
    title: placeholder
    version: 1.0
    /users:
      get:
        description: Retrieve a list of all the users
        responses:
          200:
            body:
              application/json:
                example: !include user-example.json
      /userbyid:
        get:
          description: Get information about a particular user
          queryParameters:
            id:
              description: Specify the id of the user you want to retrieve
              type:        integer
              required:    false
              example: 3
          responses:
            200:
              body:
                application/json:
                  example: |
                    [{
                    "id": 3,
                    "name": "Clementine Bauch",
                    "username": "Samantha",
                    "email": "Nathan@yesenia.net",
                    "address": {
                      "street": "Douglas Extension",
                      "suite": "Suite 847",
                      "city": "McKenziehaven",
                      "zipcode": "59590-4157",
                      "geo": {
                        "lat": "-68.6102",
                        "lng": "-47.0653"
                      }
                    },
                    "phone": "1-463-123-4447",
                    "website": "ramiro.info",
                    "company": {
                      "name": "Romaguera-Jacobson",
                      "catchPhrase": "Face to face bifurcated interface",
                      "bs": "e-enable strategic applications"
                    } }]
  4. Save it as api.raml.

Was this article helpful?

💙 Thanks for your feedback!

Edit on GitHub