I have below requirement for designing simple RAML. I’m newbie in RAML coding so would like to know if my code is according to requirement or not
Requirement:
Has at least 1 endpoint with a GET and POST method.
Includes description attribute of the API
Includes description attribute of the method
The GET request takes a query parameter of "mulesoft"
Define the response with an object that contains least a string and
integer data type
Includes an example for a 200 response code that matches the
definition’s response object from above
My code:
#%RAML 1.0
title: Coding_Champions
version: 1.0.development
baseUri: http://localhost:8004/api
description: This API displays and adds Organisation with details
types:
Org:
type: object
properties:
name: string
address: string
pincode: integer
/details:
displayName: Company Details
description: Coding challenge which takes query parameter of "mulesoft"
get:
description: Retrieve a list of all the Orgs
queryParameters:
mulesoft:
description: Specify the Org name that you want to retrieve
type: boolean
required: true
responses:
200:
body:
application/json:
type: Org
examples:
MuleSoft:
name: MuleSoft
address: 77 Geary Street, Suite 400
pincode: 94108
post:
description: Add a Org to list
body:
application/json:
type: Org
examples:
Cognizant:
name: Cognizant
address: DLF
pincode: 9771
responses:
201:
body:
application/json:
example: |
{
"message":"New Org updated but not really"
}
I’m more of concerned with one of point in the requirement
"The GET request takes a query parameter of “mulesoft”
Does it mean I should give mulesoft as parameter dynamically in my url, If yes then other than mulesoft is passed as parameter then it should throw an error ?
(or)
Does it mean i need to hard code “mulesoft” in my RAML code as I have done now ?
Can you please clear me on this ?
Does it mean I need to hard code “mulesoft” in my RAML code as I have
done now ?
Yes.You should define that in RAML as you are doing right now.Since its required parameter,its presence could be validated in implementation.
Related
I have the following endpoints configured for managing types of food
POST ~ /food/types
GET ~ /food/types
GET ~ /food/types/{id}
PUT ~ /food/types/{id}
Delete ~ /food/types/{id}
I'm trying to represent a clone operation in my REST API and wanted to avoid the use of Verbs in my endpoints.
After some research I've come up with the following as it conforms the most out of other solutions i could think of to basic REST principles:
POST ~ /food/types?sourceId={id}
This would mean that the method for this endpoint (in a typical MVC framework) would need to conditionally handle both the creation when a JSON payload is sent, and the duplication of a resource when a query parameter is provided.
I'm trying to think how i can express that in my OpenAPI specification document (v3.0.2)
Here is what i've got so far:
/api/food/types:
post:
summary: Create a new type of food
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: ./response/food-type.yaml
'400':
description: Bad Request
requestBody:
content:
application/json:
schema:
$ref: ./request/food-type.yaml
description: Create a new type of food
tags:
- Food Type
parameters: []
The request/food-type.yaml contains an object with two required parameters:
Name,
Category
When my framework validates the request against the OpenAPI specification, i want it to sometimes ignore the request body if and only if, a request parameter has been provided with a 'sourceId' parameter.
Is this type of thing even possible to express in OpenAPI 3+, or am i going about this the wrong way?
Simply put, is it possible to ignore the request body when a specific query parameter has been provided in a post request using OpenAPI 3.
And following that question, is my approach to REST lacking, and is there a better way i could represent the cloning of a resource in my API?
Use the body of the message instead to describe the source:
POST /food/types {"clone": "{id}"}
You can even use verb if you convert them into nouns:
POST /food/type-cloning {"source": "{id}"}
Is it possible to add a note to the field where the Request Samples show on Swagger UI?
My API is described in the following way:
/v1/test:
post:
summary:test
tags:
- test
description: test
parameters:
- in: body
name: body
required: false
schema:
$ref: '#/definitions/test'
x-code-samples:
- lang: cURL
source: >-
When the yaml is rendered by our UI program, the Request sample is shown like this:
sample request
Is it possible to add a note someplace marked in red on the image?
I have tried adding x-description and x-summary, but that doesn't work.
I wonder if this is possible at all.
Thank you
For example if i have:
paths:
\some:
post:
description: Sample request
parameters:
- in: header
name: firstHeader
schema:
type: string
How can I add this header in every request, without repeating this code? I've tried to reference as object after parameters, but in that case it won't be part of the headers of the request.
[enter image description here][1]I know my syntax is wrong in the image here . But just want to let you know what I'm trying to achieve.I'm using RAML 0.8. I want to include multiple requests and responses for a single resource. Can this be achieved in RAML 0.8? Your response is much appreciated. Thank you!
You can have multiple responses in RAML 0.8, for example one for the 200 status code, one for the 404 status code, etc.
An example of this is:
/media/popular:
displayName: Most Popular Media
get:
description: |
Get a list of what media is most popular at the moment.
responses:
200:
body:
application/json:
schema: !include instagram-v1-media-popular.schema.json
503:
description: |
The service is currently unavailable or you exceeded the maximum requests
per hour allowed to your application.
body:
application/json:
schema: !include instagram-v1-meta-error.schema.json
You can specify several requests, but each for a different media type.
For example:
/jobs:
post:
description: Create a Job
body:
text/xml: !!null
application/json: !!null
You cannot have multiple examples in 0.8.
(In RAML 1 you can have multiple examples)
I am receiving an issue with a datatype .raml file that I am attempting to create. For some reason, it is stating that I am 'Specifying unknown facet 'types' as an error.
What is the proper way to go about defining an object in RAML?
#%RAML 1.0 DataType
types:
Account:
type: object
displayName: Account
description: Salesforce Account Object
properties:
id:
type: string
description: Id of the Salesforce Account
ns_id:
type: string
description: Id of NetSuite Customer
name:
type: string
description: Name of Salesforce Account
phone:
type: string
description: Phone Number of Salesforce Account
website:
type: string
description: Website of the Salesforce Account
owner:
type: string # This probably needs to be of type Owner
description: Owner of Account
active_cmrr:
type: number
description: Active CMRR of Account
billing_address:
type: string
description: Billing Address of Account
subscription_start_date:
type: date-only
description: Salesforce Account Subscription Start Date
subscription_end_date:
type: date-only
description: Salesforce Account Subscription End Date
#Sometype of Opportunity list
#opportunities:
# type: Opportunity[]
# description: List of Account Opportunities
You are currently using a so called RAML fragment which focuses on a single definition only. In your case a single type definition.
You start defining multiple type definitions usually using types either in a root RAML file (indicated with #%RAML 1.0) or in a library (indicated with #%RAML 1.0 Library). So depending on what you try to achieve you either modify your data type fragment to only contain the definition of the Account type or you change #%RAML 1.0 DataType to #%RAML 1.0 Library so you can package multiple type definition into one; or you use both for max reusability.
Let me show you how to use both:
account.raml
#%RAML 1.0 DataType
type: object
displayName: Account
description: Salesforce Account Object
properties:
id:
type: string
description: Id of the Salesforce Account
ns_id:
type: string
description: Id of NetSuite Customer
name:
type: string
description: Name of Salesforce Account
phone:
type: string
description: Phone Number of Salesforce Account
website:
type: string
description: Website of the Salesforce Account
owner:
type: string # This probably needs to be of type Owner
description: Owner of Account
active_cmrr:
type: number
description: Active CMRR of Account
billing_address:
type: string
description: Billing Address of Account
subscription_start_date:
type: date-only
description: Salesforce Account Subscription Start Date
subscription_end_date:
type: date-only
description: Salesforce Account Subscription End Date
#Sometype of Opportunity list
#opportunities:
# type: Opportunity[]
# description: List of Account Opportunities
types.raml
#%RAML 1.0 Library
types:
Account: !include account.raml
In other type definition you could then use the library to reference to the account type. For example:
bank.raml
#%RAML 1.0 DataType
uses:
types: types.raml
type: object
properties:
branch: string
accounts:
type: array
items: types.Account
Hope that helps you! Let me know if you have any further questions.