Support for RAML 1.0 Data Types in Datasense
|
Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations. |
Datasense now supports RAML 1.0 data types, and can parse this information to be displayed in the DataSense explorer.
RAML 1.0 Data Types
RAML v1.0 introduced Data Types, a concise and versatile way to describe and validate data inside your API definition.
You can define a type at the beginning of your RAML file, and you can later reference that same type to describe the body of as many API requests or responses as you need. You can even define a data type to inherit properties of another type within your API.
Think of data types as a define once, use many schema-like definition.
Datasense now supports data types inheritance along with XML and JSON schema propagation across your RAML 1.0 API description, allowing the Datasense explorer to correctly display the metadata generated by your RAML file including fields and types inherited from your type declarations.
Example
Consider a simple example of an API that serves and populates resources with contact information from two different types of contacts: companies and individuals.
Using Data Types, you can define a contact type, with properties address and email information. You can also define specific properties for each contact information property.
In RAML 1.0 it would look like this:
#%RAML 1.0
title: Contact Information API
mediaType: application/json
types:
###############
# Contacts Data:
###############
Contact:
properties:
address:
type: Address
email:
type: Email
Address:
properties:
street:
type: string
city:
type: string
state:
type: string
country:
type: string
Email:
pattern: ^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,4})$Now you can define individuals and companies leveraging their contact-information property in the data types defined earlier:
###############
# Contacts:
###############
Individual:
properties:
name:
type: string
contact-information:
type: Contact
Company:
properties:
company-name:
type: string
contact-information:
type: ContactFinally, for the API definition, you can define get and post methods for both resources (`/individuals`and `/companies):
###############
# API:
###############
/individuals:
get:
responses:
200:
body:
type: Individual
example: |
{
"name": "Max",
"contact-information": {
"address": {
"street":"Market Street",
"city":"San Francisco",
"state":"California",
"country":"United States"
},
"email":"max@mail.com"
}
}
post:
body:
type: Individual
responses:
200:
body:
example: |
{
"name":"",
"contact-information": {
"address": {
"street":"",
"city":"",
"state":"",
"country":""
},
"email": ""
}
}
/companies:
get:
body:
type: Company
responses:
200:
body:
type: Company
example: |
{
"company-name": "MuleSoft",
"contact-information": {
"address": {
"street":"77 Geary St.",
"city":"San Francisco",
"state":"California",
"country":"United States"
},
"email":"mulesoft@mail.com"
}
}
post:
body:
type: Company
responses:
200:
body:
example: |
{
"company-name": "",
"contact-information": {
"address": {
"street":"",
"city":"",
"state":"",
"country":""
},
"email":""
}
}If you download this RAML definition example, import it into Studio, add logger processor at any of the generated flows and inspect the input displayed by the DataSense Explorer, you can see the metadata populated considering al the types definition and inheritance.
This is how it looks when inspecting the GET method for the /companies resource:
DataSense even recognizes if you change the API’s mediaType to application/xml:
Datasense can even handle XML attribute type declarations. Such as:
Company:
properties:
company-name:
type: string
xml:
attribute: true
name: xmlname
contact-information:
type: Contact