Permalink
Browse files

Initial RAML spec content

Initial commit of the RAML spec.
  • Loading branch information...
comptly committed Sep 30, 2013
1 parent 19eee71 commit 551cc132be8066dd53b4ac1253c76bc0f8417e35
Showing with 1,610 additions and 3 deletions.
  1. +67 −0 01_introduction.md
  2. +68 −0 02_includes.md
  3. +108 −0 03_named_parameters.md
  4. +233 −0 04_basic_information.md
  5. +436 −0 05_resources_and_methods.md
  6. +218 −0 06_schemas_and_responses.md
  7. +232 −0 07_resource_types_and_traits.md
  8. +172 −0 08_security.md
  9. +58 −0 09_references.md
  10. +12 −0 Makefile
  11. +6 −3 README.md
View
@@ -0,0 +1,67 @@
+RAML™ Version 0.2: RESTful API Modeling Language
+===================================
+
+
+Abstract
+--------
+
+RAML™ is a YAML-based language that describes RESTful APIs. Together with the [YAML specification](http://yaml.org/spec/1.2/spec.html), this specification provides all the information necessary to describe RESTful APIs; to create API client-code and API server-code generators; and to create API user documentation from RAML API definitions.
+
+
+Introduction
+------------
+
+This specification describes RAML. RAML is a human-readable and machine process-able description of a RESTful API interface. API documentation generators, API client-code generators, and API servers consume a RAML document to create user documentation, client code, and server code stubs, respectively.
+
+Conventions
+-----------
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].
+
+Overview
+--------
+
+RAML defines the media type "application/raml+yaml" for describing and documenting a RESTful API's resources, such as the resources' methods and schema. RAML is YAML-based, and RAML documents support all YAML 1.2 features. The recommended filename extension for RAML files is ".raml".
+
+RAML also provides facilities for extensively documenting a RESTful API, enabling documentation generator tools to extract the user documentation and translate it to visual formats such as PDF, HTML, and so on.
+
+RAML also introduces the innovative concept of resource types and traits for characterizing resources and methods, thereby minimizing the amount of repetition required to specify a RESTful API's design.
+
+This RAML Specification is organized as follows:
+
+* **Basic Information.** Explains how to describe core aspects of a RESTful API, such as is name, title, and location.
+* **User Documentation.** Describes how to include supporting documentation for the RESTful API.
+* **Resource Types and Traits.** Describes the optional mechanism for using RAML resource types and traits to characterize resources so as to avoid unnecessary repetition in the RESTful API's definition.
+* **Resources.** Describes how to specify a RESTful API's resources, resources' methods and schema, and the interactions between resources.
+
+
+### Terminology
+
+For this specification, *API definition* will be used to denote the description of an API using this specification and *RAML Specification* refers to the current document.
+
+### REST
+
+*REST* is used in the context of an API implemented using the principles of REST. The REST acronym stands for Representational State Transfer and was first introduced and defined in 2000 by Roy Fielding in his doctoral dissertation [REST].
+
+### Resource
+
+A *resource* is the conceptual mapping to an entity or set of entities.
+
+Markup Language
+---------------
+
+This specification uses YAML 1.2 [YAML] as its core format. YAML is a human-readable data format that aligns well with the design goals of this specification.
+
+RAML API definitions are YAML-compliant documents that begin with a REQUIRED YAML-comment line that indicates the RAML version, as follows:
+
+```yaml
+#%RAML 0.2
+---
+```
+
+The RAML version MUST be the first line of the RAML document. RAML parsers MUST interpret all other YAML-commented lines as comments.
+
+In RAML, the YAML data structures are enhanced to include data types that are not natively supported. All RAML document parsers MUST support these extensions.
+
+In RAML, all values MUST be interpreted in a case-sensitive manner.
+
View
@@ -0,0 +1,68 @@
+### Includes
+
+The YAML specification does not require that YAML parsers use any particular mechanism for splitting a YAML file into smaller manageable pieces. However, RAML documents MUST be able to be split among multiple files. To support this function, all RAML parsers MUST support the *include* tag, which enables including RAML and YAML and regular text files.
+
+In this example, the content of myTextFile.txt is included as the value of the external property.
+
+```yaml
+#%RAML 0.2
+---
+external: !include myTextFile.txt
+```
+
+When RAML or YAML files are included, RAML parsers MUST not only read the content, but parse it and add the content to the declaring structure as if the content were declared inline.
+
+To simplify API definition, and because the included file's parsing context is not shared between the included file and its parent, an included file SHALL NOT use a YAML reference to an anchor in a separate file. Likewise, a reference made from a parent file SHALL NOT reference a structure anchor defined in an included file.
+
+In this example, the *properties.raml* file defines two properties. The *big.raml* file includes the properties.raml file.
+
+```yaml
+#%RAML 0.2
+---
+#properties.raml
+
+propertyA: valueA
+propertyB: valueB
+```
+
+```yaml
+#%RAML 0.2
+---
+#big.raml
+
+external: !include properties.raml
+```
+
+The resulting structure is equivalent to the following inline declaration:
+
+```yaml
+#%RAML 0.2
+---
+external:
+ propertyA: valueA
+ propertyB: valueB
+```
+
+If a relative path is used for the included file, the path is interpreted relative to the location of the original (including) file. If the original file is fetched as an HTTP resource, the included file SHOULD be fetched over HTTP.
+
+In the following example, because the original (including) file is located at *http://example-domain.org/api/example.raml*, the *properties.raml* file should be fetched from *http://example-domain.org/api/properties.raml*.
+
+```yaml
+#%RAML 0.2
+---
+#http://example-domain.org/api/example.raml
+
+external: !include properties.raml
+```
+
+If the included file has one of the following media types:
+
+* application/raml+yaml
+* text/yaml
+* text/x-yaml
+* application/yaml
+* application/x-yaml
+
+or a *.raml* or *.yml* or *.yaml* extension, RAML parsers MUST parse the content the file as RAML content and append the parsed structures to the RAML document's node.
+
+The location of the file to be included, that is, the right-hand side of !include, must be static, that is, it cannot contain any resource type or trait parameters. This will be reconsidered for future versions of RAML.
View
@@ -0,0 +1,108 @@
+Named Parameters
+----------------
+
+This RAML Specification describes collections of named parameters for the following properties: URI parameters, query string parameters, form parameters, request bodies (depending on the media type), and request and response headers. All the collections specify the named parameters' attributes as described in this section.
+
+Some named parameters are optional and others are required. See the description of each named parameter.
+
+Unless otherwise noted, named parameter values must be formatted as plain text. All valid YAML file characters MAY be used in named parameter values.
+
+
+### displayName
+(Optional)
+The *displayName* attribute specifies the parameter's display name. It is a friendly name used only for display or documentation purposes. If *displayName* is not specified, it defaults to the property's key (the name of the property itself).
+
+### description
+(Optional)
+The *description* attribute describes the intended use or meaning of the parameter. This value MAY be formatted using Markdown [MARKDOWN].
+
+### type
+(Optional)
+The *type* attribute specifies the primitive type of the parameter's resolved value. API clients MUST return/throw an error if the parameter's resolved value does not match the specified type. If *type* is not specified, it defaults to string. Valid types are:
+
+| Type | Description |
+|:--------|:------------|
+| string | Value MUST be a string.
+| number | Value MUST be a number. Indicate floating point numbers as defined by YAML.
+| integer | Value MUST be an integer. Floating point numbers are not allowed. The integer type is a subset of the number type.
+| date | Value MUST be a string representation of a date as defined in RFC2616 Section 3.3 [RFC2616]. See [Date Representations](#date-representations).
+| boolean | Value MUST be either the string "true" or "false" (without the quotes).
+| file | (Applicable only to Form properties)<br><br>Value is a file. Client generators SHOULD use this type to handle file uploads correctly.
+
+##### Date Representations
+As defined in [RFC2616], all date/time stamps are represented in Greenwich Mean Time (GMT), which for the purposes of HTTP is equal to UTC (Coordinated Universal Time). This is indicated by including "GMT" as the three-letter abbreviation for the timezone. Example: ```Sun, 06 Nov 1994 08:49:37 GMT```.
+
+
+### enum
+(Optional, applicable only for parameters of type string)
+The *enum* attribute provides an enumeration of the parameter's valid values. This MUST be an array. If the *enum* attribute is defined, API clients and servers MUST verify that a parameter's value matches a value in the *enum* array. If there is no matching value, the clients and servers MUST treat this as an error.
+
+### pattern
+(Optional, applicable only for parameters of type string)
+The *pattern* attribute is a regular expression that a parameter of type string MUST match. Regular expressions MUST follow the regular expression specification from ECMA 262/Perl 5. The pattern MAY be enclosed in double quotes for readability and clarity.
+
+### minLength
+(Optional, applicable only for parameters of type string)
+The *minLength* attribute specifies the parameter value's minimum number of characters.
+
+### maxLength
+(Optional, applicable only for parameters of type string)
+The *maxLength* attribute specifies the parameter value's maximum number of characters.
+
+### minimum
+(Optional, applicable only for parameters of type number or integer)
+The *minimum* attribute specifies the parameter's minimum value.
+
+### maximum
+(Optional, applicable only for parameters of type number or integer)
+The *maximum* attribute specifies the parameter's maximum value.
+
+### example
+(Optional)
+The *example* attribute shows an example value for the property. This can be used, e.g., by documentation generators to generate sample values for the property.
+
+### repeat
+(Optional)
+The *repeat* attribute specifies that the parameter can be repeated. If the parameter can be used multiple times, the *repeat* parameter value MUST be set to 'true'. Otherwise, the default value is 'false' and the parameter may not be repeated.
+
+### required
+(Optional except as otherwise noted)
+The *required* attribute specifies whether the parameter and its value MUST be present in the API definition. It must be either 'true' if the value MUST be present or 'false' otherwise.
+
+In general, parameters are optional unless the *required* attribute is included and its value set to 'true'.
+
+For a URI parameter, the *required* attribute MAY be omitted, but its default value is 'true'.
+
+### default
+(Optional)
+The *default* attribute specifies the default value to use for the property if the property is omitted or its value is not specified. This SHOULD NOT be interpreted as a requirement for the client to send the *default* attribute's value if there is no other value to send. Instead, the *default* attribute's value is the value the server uses if the client does not send a value.
+
+## Named Parameters With Multiple Types
+To denote that a named parameter can have multiple types, the value of the named parameter property MAY be an array of mappings, each of which has the attributes described in this document. This mechanism for defining a parameter with multiple types is particularly useful when an API uses the same named parameter for more than one data type.
+
+In the following example, the named parameter *file* can be used for sending a file or string text data to an API:
+
+```yaml
+#%RAML 0.2
+---
+title: Amazon simple storage API
+version: 1
+baseUri: https://{destinationBucket}.s3.amazonaws.com
+/:
+ post:
+ description: The POST operation adds an object to a specified bucket using HTML forms.
+ 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.
+```
Oops, something went wrong.

0 comments on commit 551cc13

Please sign in to comment.