The X-Factor: RAML With XML Format

In this article, we will explore how RAML specifications can be defined for the XML representation of resources. This will be explained with the help of JOB API. Consider this API for the purpose of getting a list of all jobs published by different companies. A job can also be posted using this JOB API.

JOB API

• Resource: Jobs
• Resource Path: /jobs
• Methods:
  • GET: To retrieve a list of all jobs
  • POST:  To add a job

JSON Representation

Let's start with JSON.  RAML Specification with media type as application/JSON is shown below:

Data type fragment of job data type:

Test GET method of/jobs using Mocking Service. The response is:

But now we want the representation of the job resource in XML format also.

XML Representation

Let's specify the media type as application/XML:

Test the GET method using the Mocking service. Specify the accept header value as application/XML. The response will be:

Simple!! Right?

Changing Root Tag

Now we don't want our root tag to be model. So let's change it to jobs. Specify the name using XML node as shown below:

Test using Mocking Service again with Accept Header value as application/XML. The response is:

Location Data Type

Now we want to specify the Location where this job is applicable.

So let's create a Location Data Type. Location Data Type fragment is:

Job Data Type is updated with Location property and it is defined using Location data type fragment:

Example fragments are also updated. One of the example fragments is shown below:

Test using Mocking Service again. The response is:

Now, let's change the name of the location tag to JobLocation :

Let's test using Mocking Service again. Now the response is:

Attributes

Let's make JobTitle the attribute of the job tag. So change the job data type as follows:

No change in examples. Test using Mocking Service. The response is:

POST Method

In case you are wondering what the POST request looks like in our scenario, take a look:

JSON

Let's check what the GET Response looks like with JSON Representation after all these changes. Test using Mocking Service with Accept header value as application/JSON. The response is:

We have defined RAML to have resource representation in both XML and JSON.

Happy X-Factoring!