Software AG Products 10.7 | Using CentraSite | Asset Management | RAML to CentraSite REST API Mappings
 
RAML to CentraSite REST API Mappings
This section describes how the RAML objects and properties (as described in the RAML specification) are mapped in the CentraSite REST data model. It shows the relationships between the RAML root section, parameters, body fields, and their REST data model. It also lists the relationships between RAML resources, methods, reference documentation, and security schemes, and how these values are mapped in REST API.
Note:
CentraSite supports RAML version 0.8.
The following tables list the correspondences (mappings) between the fields of a RESTful API and RAML document:
RAML Root Section Fields
The root section of the RAML definition describes the basic information of a RESTful API, such as its title, version, base URI, default media types, and common schema references.
RAML Root Section Field
REST API Field
Notes
RAML Document
REST Service
The RAML Document property is represented by an asset of type REST Service in the CentraSite registry.
The RAML Document is stored as a file attribute in the Documents field of the Specification profile in the REST API's details page.
One or more RAML documents can be attached to a REST API. The attached documents are stored in the asset-specific WebDAV folder like the schema and WSDL documents.
API Title
Name
The API Title property is represented by the Name field in the REST API's details page.
API Version
Version
API Version is represented by the Version field in the REST API's details page.
Server URI
Server URL
The Server URI property is represented by the Server URL field in the Technical Details profile.
Server Variables
The Server Variables are given as part of Server URL.
Protocols
Server URLs
In CentraSite, the Protocols property is represented by the multiple Server URL fields of the Technical Details profile. The URLs formed are considered as REST Server.
Example:
A RAML Specification:
baseUri:
http://products.api.apievangelist .com protocols:[HTTP, HTTPS]
Reads in CentraSite REST Model:
http://products.api. apievangelist.com
https://products.api. apievangelist.com
Default Media Type
Request Content Type
Response Content Type
In CentraSite, the Default Media Type property is represented by the Request Content-Type and Response Content-Type fields of the Technical Details in the REST API's details page.
Schemas
Schema
The Schemas property is represented by the Request Schema or Response Schema field of a REST Method.
REST Parameters (for Server Uri)
The REST Parameters is represented byServer Variables and are given as part of Server URL.
User Documentation
Description
The User Documentation property is represented by the Description field in the REST API's details page.
RAML Parameter Fields
The following tables show the mappings between various RAML parameter types, data types, and attributes and how they are used by REST API. The mappings are grouped into tables for RAML Parameter Types, RAML Parameter Data Types, and RAML Parameter Attributes:
RAML Parameter Types
RAML Parameter Field
REST API Field
Notes
URI Parameter
Parameter of type, Path
The URI Parameter property is represented by the Path option in the Parameter Type field of a REST Parameter, and is specifically defined at the Resource level. Any URI Parameter defined at the API level or Method level is not mapped in CentraSite.
Query Parameter
Parameter of type, Query-String
The QueryParameter property is represented by the Query-String option in the Parameter Type field of a REST Parameter.
Header
Parameter of type, Header
The Header property is represented by the Header option in the Parameter Type field of a REST Parameter.
Form Parameter
Parameter of type, Form
The Form Parameter property is represented by the Form option in the Parameter Type field of a REST Parameter.
RAML Parameter Data Types
RAML Data Type Field
REST API Field
Notes
string
String
The string property is represented by the String option in the Data Type field of a REST Parameter.
number
Number
The number property is represented by the Number option in the Data Type field of a REST Parameter.
integer
Number
The integer property is represented by the Number option in the Data Type field of a REST Parameter.
date
Date/Time
The date property is represented by the Date/Time option in the Data Type field of a REST Parameter.
boolean
Boolean
The boolean property is represented by the Boolean option in the Data Type field of a REST Parameter.
file
URL/URI
Currently, CentraSite does not support parameter of the data type file.
RAML Parameter Attributes
RAML Attribute Field
REST API Field
Notes
enum
Possible Values
The enum property is represented by the Possible Values field of a REST Parameter.
required
Required
The required property is represented by the Required field of a REST Parameter.
default
Default Value
The default property is represented by the Default Value field of a REST Parameter.
pattern
Currently, CentraSite does not support the pattern attribute.
minLength
Currently, CentraSite does not support the minLength attribute.
maxLength
Currently, CentraSite does not support the maxLength attribute.
minimum
Currently, CentraSite does not support the minimum attribute.
maximum
Currently, CentraSite does not support the maximum attribute.
example
Currently, CentraSite does not support the example attribute.
repeat
The repeat property is represented by the Array field of a REST Parameter.
RAML Resource Fields
RAML resource properties (data) are mapped to the REST API resource objects. The following table shows the resource mappings between a RAML definition and a REST API:
RAML Resource Field
REST API Field
Notes
Resource
REST Resource
The Resource property is represented by an asset of type REST Resource in the CentraSite registry.
Resource Relative Path
Resource Path
The Resource Relative Path property is represented by the Resource Path field of a REST Resource.
Display Name
Name
The Display Name property is represented by the Name field of a REST Resource.
Description
Description
The Description property is represented by the Description field of a REST Resource.
Template URIs
Resource Path with Path parameter
The Template URI property is represented by the Resource Path field which has the Path parameter appended to it, and is defined as a REST Resource object.
URI Parameters
Parameter of type, Path
The URI Parameter property is defined as a REST Parameter object of the type Path at the REST Resource level.
Base URI Parameters
Currently, CentraSite does not support mapping URI Parameter property at the Base URL level.
Resource Types and Traits
Limitation: Resource Types and Traits are not explicitly mapped to the REST API; instead, propagated to the referencing REST Resources and REST Methods.
RAML Method Fields
The following tables show the mappings between various RAML method objects, bodies and responses, and how they are used by REST API. The mappings are grouped into tables for RAML Method Headers, RAML Method Body, and RAML Method Responses:
RAML Method Headers
RAML Method Header Field
REST API Field
Notes
Method
REST Method
The Method property is represented by an asset of type REST Method in the CentraSite registry.
Description
Description
Description property is represented by the Description field of a REST Method.
Header
Parameter of type "Header"
The Header property is defined as a REST Parameter object of the type Header at the REST Resource level.
Protocols
Currently, CentraSite does not support mapping Protocol property at the REST Method level.
Query Parameters
Parameter of type "Query-String"
The QueryParameters property is defined as a REST Parameter object of the type Query-String at the REST Resource level.
RAML Method Body
RAML Method Body Field
REST API Field
Notes
Body
Request
The Body property is defined as the Request Payload object.
CentraSite automatically populates the Media type as Name of a REST Payload object.
Media type
Request Content-Type
Response Content-Type
The Media type property is represented by the Request Content-Type or Response Content-Type field of a REST Payload object.
Schema
Schema
The Schema property is represented as REST Schema objects for Request or Response objects.
Example
Example
The Example property is represented as REST Example objects for Request or Response objects.
RAML Method Responses
RAML Method Response Field
REST API Field
Notes
HTTP status code
REST Payload
The HTTP status code property is defined as the REST Payload object of a REST Method.
CentraSite automatically populates the HTTP status code as the Name of a REST Payload object.
Example
Response Example
The Example property is represented by the Response Example field of a REST Payload object.
Description
Description
The Description property is represented by the Response Description field of a REST Payload object.
Body
Response Content-Type
The Body property is represented by the Response Content-Type field of a REST Payload object.
Body media type
Response Content-Type
The Body Media type property is represented by the Response Content-Type field of the REST Payload.
RAML Resource Type and Trait Fields
All RAML resource types and traits properties are not explicitly mapped to the REST API. Instead, the RAML resource types are propagated to the referencing document structure named REST Resource and RAML traits are propagated to the document structure named REST Method.
RAML Security Scheme Fields
RAML security schemes are not explicitly mapped to the REST API. Instead, the RAML security schemes are propagated to the taxonomy structure named Security Types, and represented by the Supported Access Token Types property defined in the API Portal Information profile.
Security Type
Description
API Key
The API's authentication requires using an API key.
Basic Authentication
The API's authentication requires using Basic Access Authentication as described in RFC2617.
Digest Authentication
The API's authentication requires using Digest Access Authentication as described in RFC2617.
OAuth 1.0
The API's authentication requires using OAuth 1.0 as described in RFC5849.
OAuth 2.0
The API's authentication requires using OAuth 2.0 as described in RFC6749.
x-{other}
The API's authentication requires using another authentication method.
The supported security schemes along with their scheme reference name are mapped in the CentraSite registry. For more information about the security scheme, see the RAML specification.