Skip to content

Instantly share code, notes, and snippets.

@softmentor

softmentor/helloworld.raml

Last active December 27, 2015 02:18
Show Gist options
  • Save softmentor/7250896 to your computer and use it in GitHub Desktop.
Save softmentor/7250896 to your computer and use it in GitHub Desktop.
Download ZIP
Hello World RAML file
Raw
helloworld.raml
#%RAML 0.8
---
#===============================================================
# Example Hello World API - RAML example
# References:
# - RAML Specification - http://raml.org/spec.html
# - RAML Projects - http://raml.org/projects.html
# - RAML Tools - http://www.apihub.com/raml-tools
#===============================================================
title: Example Hello World API
version: v0.1
baseUri: http://{productName}.{domainName}.{domainSuffix}/{apiName}
baseUriParameters:
domainName:
displayName: Company Domain name
type: string
maxLength: 100
required: true
default: localhost
description: Name of the company domain for apis. example companyapis.com or companyapis.io
domainSuffix:
displayName: Domain Suffix
description:
enum: [ "com", "io" ]
productName:
displayName: Product Name
type: string
#Only small case names
pattern: ^[a-z][-a-z]*$
minLength: 3
maxLength: 10
default: app
required: true
description: A abreviated product name is given as sub-domain.
apiName:
displayName: Api Name
type: string
pattern: ^[a-zA-Z0-9][-a-zA-Z0-9]*$
minLength: 3
maxLength: 100
required: true
default: api
description: This defines the api name. example, users or events etc.
#List of media type to support
mediaType: application/json
#List of protocols to support for baseUri
protocols: [ HTTP, HTTPS ]
#baseUri parameter schemes
#===============================================================
# API documentation
#===============================================================
documentation:
- title: Home
content: | #Can have markdown text here.
Welcome to the _Example API_ Documentation. The _Example API_
allows you to connect your application to our product services
without going through the web interface. You
may also benefit from one of our
[integration libraries](https://app.company.com/docs/faq/basics/libraries)
for different languages.
#content: !include company-home.md
- title: Getting Started
content: TODO
#content: !include get-started.md
#===============================================================
# API schema references
#===============================================================
schemas:
#- !include path-to-canonical-schemas/helloWorld_schemas.raml
# Inline schema definitions, map of "key values"
- User: schema/user.json
Users: schema/users.json
Book: schema/book.json
Books: schema/books.json
#===============================================================
# API common resource type definitions. These are partial resource definitions which are repeated.
# Resources that use a resource type inherit its properties, such as its description, methods etc.
#===============================================================
resourceTypes:
#- !include company/standardResourceTypes.yaml # where standardResourceTypes.yaml is a map of standard resource type definitions
#- !include app/resourceTypes/specialCollection.yaml # where specialCollection.yaml defines one resource type
#Inline definitions
- collection:
usage: This resourceType should be used for any collection of items
description: The collection of <<resourcePathName>>
get:
description: Get all <<resourcePathName>>, optionally filtered
post:
description: Create a new <<resourcePathName | !singularize>>
# Remote definitions
#- collection: !include resourceTypes/app-collection.yaml
#- member: !include resourceTypes/app-member.yaml
# OR shorter version
#resourceTypes: !include resourceTypes/allResourceTypes.yaml # where allResourceTypes.yaml is an array of maps of resource type definitions
- searchableCollection:
get:
queryParameters:
<<queryParamName>>:
description: Return <<resourcePathName>> that have their <<queryParamName>> matching the given value
<<fallbackParamName>>:
description: If no values match the value given for <<queryParamName>>, use <<fallbackParamName>> instead
# Some Advance Usage
#TODO
#===============================================================
# API common trait definitions. These are partial method definition that,
# like a method, can provide method-level properties such as:
# description, headers, query string parameters, and responses.
# Methods that use one or more traits inherit those traits' properties.
#===============================================================
traits:
#- !include company/standardTraits.yaml # where standardTraits.yaml is a map of standard trait definitions
#- !include app/traits/specialTraits.yaml # where specialTraits.yaml defines special traits for the app
#Inline definitions
- secured:
<<tokenName>>: A valid <<tokenName>> is required
usage: Apply this to any method that needs to be secured
description: Some requests require authentication.
queryParameters:
access_token:
description: Access Token
type: string
example: ACCESS_TOKEN
required: true
- paged:
queryParameters:
numPages:
description: The number of pages to return, not to exceed <<maxPages>>
# Remote definitions
#- secured: !include traits/secured.yaml
#- rateLimited: !include traits/rate-limited.yaml
# OR shorter version
#traits: !include traits/allTraits.yaml # where allTraits.yaml is an array of maps of trait definitions
#securitySchemes:
#- oauth_2_0: !include security/oauth_2_0.yml
#- oauth_1_0: !include security/oauth_1_0.yml
#- custom_auth_1_0: !include security/customauth_1_0.yml
#===============================================================
# API resource definitions
#===============================================================
/users: # its fully-resolved URI is https://app.companyapis.com/api/{version}/users
type: { collection : {resourcePathName: users} } #inherits from resourceTypes definitions, in this case "collection" resourceType
is: [ secured : { tokenName: access_token } ] # if collection defines a post method, that method is also secured
uriParameters:
displayName: Users
description: A collection of users #Can have markdown text here.
post:
description: Create a user
#Post body media type support
#text/xml: !!null # media type text, xml support
#application/json: !!null #media type json support
body:
text/xml:
#schema: !include schema/user.xsd
schema: | #Form post content type schema definition for xml
<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="user">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="userName"/>
<xs:element type="xs:string" name="userEmail"/>
<xs:element type="xs:string" name="userPhone"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
example: |
<user>
<userName>testUser</userName>
<userEmail>testUser@mymail.com</userEmail>
<userPhone>+14158675309</userPhone>
</user>
application/json:
#schema: !include schema/user.json
schema: | #Form post content type schema definition for json
{
"$schema": "http://json-schema.org/draft-03/schema",
"user": {
"userName": {
"required": true,
"type": "string"
}
"userEmail": {
"required": true,
"type": "string"
}
"userPhone": {
"required": true,
"type": "string"
}
},
"required": true,
"type": "object"
}
example: |
{
"user": {
"userName": "testUser",
"userEmail": "testUser@mymail.com",
"userPhone": "+14158675309"
}
}
get:
is: [ paged : {maxPages: 10} ]
#securedBy: [null, oauth_2_0: { scopes: [ ADMINISTRATOR ] } ] #Auth security schemes applied
description: Get a list of users
queryParameters:
page:
description: Specify the page that you want to retrieve
type: integer
required: true
example: 1
per_page:
description: Specify the amount of items that will be retrieved per page
type: integer
minimum: 10
maximum: 200
default: 30
example: 50
responses:
200:
body:
application/json:
#example: !include schema/user-list.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 schema/user-list.error.json
#---------------------------------------------------------------
# Nested resource representing a single user - name parameter as part of the path.
#---------------------------------------------------------------
/{userId}: # its fully-resolved URI is https://app.companyapis.com/api/{version}/users/{userId}
description: | #Can have markdown text here
A specific user, a member of the users collection. A URI (relative to the baseUri) of "/users/123" matches the "/{userId}" resource nested within the "/users" resource, but a URI of "/users/123/x" does not match any of those resources.
uriParameters:
userId:
displayName: User ID
type: integer
#---------------------------------------------------------------
# Account nested resource API - accounts belonging to a user
#---------------------------------------------------------------
/accounts: # Nest Resource, its fully-resolved URI is https://app.companyapis.com/api/{version}/users/{userId}/account
description: An user can have multiple accounts associated.
displayName: Account resource for the given userId.
/{accountId}:
description: |
A specific accountId for the given userId. Example, "/users/123/accounts/248"
#---------------------------------------------------------------
# Books nested resource API - books belonging to a user
#---------------------------------------------------------------
/books: # Nest Resource, its fully-resolved URI is https://app.companyapis.com/api/{version}/users/{userId}/account
description: An user can have multiple books authored.
displayName: Book resource for the given userId.
/{bookId}:
description: |
A specific bookId for the given userId. Example, "/users/123/books/2av3"
#---------------------------------------------------------------
# Books API - using inherited resource types and traits (common definitions)
# It becomes quite easy to read and understand.
#---------------------------------------------------------------
/books:
type: { searchableCollection: { queryParamName: title, fallbackParamName: digest_all_fields, resourcePathName: books } }
get:
is: [ secured: { tokenName: access_token }, paged: { maxPages: 10 } ]
#---------------------------------------------------------------
# Bulk content Books API
# Still lot of TODO here
#---------------------------------------------------------------
/bulk/books:
baseUriParameters:
productName:
displayName: Product Name for bulk content apis.
type: string
#Only small case names
pattern: ^[a-z][-a-z]*$
minLength: 3
maxLength: 10
#We want bulk apis to be under a different sub-domain.
default: app-content
required: true
description: A abreviated product name is given as sub-domain.
post:
description: The POST operation adds an object to a specified bucket using HTML forms.
headers:
App-Api-Key:
displayName: App API Key
description: |
The API key for your App account. You can find your API key at
https://app.companyapis.com/api. You can also regenerate your API key on
that page.
type: string
required: true
minLength: 30
maxLength: 30
example: abcdefghijabcdefghijabcdefghij
X-App-metadata-books-{*}:
displayName: Job Metadata
description: |
Field names prefixed with X-App-metadata- contain user-specified metadata.
The API does not validate or use this data. All metadata headers will be stored
with the job and returned to the client when this resource is queried.
body:
application/x-www-form-urlencoded:
formParameters:
AWSAccessKeyId:
description: The AWS Access Key ID of the owner of the bucket who grants an Anonymous user access for a request that satisfies the set of constraints in the Policy.
type: string
acl:
description: Specifies an Amazon S3 access control list. If an invalid access control list is specified, an error is generated.
type: string
file:
- type: string
description: Text content. The text content must be the last field in the form.
- type: file
description: File to upload. The file must be the last field in the form.
responses:
200:
description: |
The list of popular media.
headers:
X-App-metadata-{?}:
description: |
Field names prefixed with x-meta- contain user-specified metadata.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment