Permalink
Browse files

Fixed #28

  • Loading branch information...
1 parent 465f36d commit 01f9c1f75177bb0720416ea74a053ced18a438b5 Damian Martinez Gelabert committed Jan 15, 2014
Showing with 97 additions and 92 deletions.
  1. +0 −1 01_introduction.md
  2. +0 −5 02_includes.md
  3. +0 −1 03_named_parameters.md
  4. +0 −11 04_basic_information.md
  5. +47 −17 05_resources_and_methods.md
  6. +0 −7 07_resource_types_and_traits.md
  7. +0 −4 08_security.md
  8. +50 −46 raml-0.8.md
View
@@ -57,7 +57,6 @@ RAML API definitions are YAML-compliant documents that begin with a REQUIRED YAM
```yaml
#%RAML 0.8
----
```
The RAML version MUST be the first line of the RAML document. RAML parsers MUST interpret all other YAML-commented lines as comments.
View
@@ -6,7 +6,6 @@ In this example, the content of myTextFile.txt is included as the value of the e
```yaml
#%RAML 0.8
----
external: !include myTextFile.txt
```
@@ -18,7 +17,6 @@ In this example, the *properties.raml* file defines two properties. The *big.ram
```yaml
#%RAML 0.8
----
#properties.raml
propertyA: valueA
@@ -27,7 +25,6 @@ propertyB: valueB
```yaml
#%RAML 0.8
----
#big.raml
external: !include properties.raml
@@ -37,7 +34,6 @@ The resulting structure is equivalent to the following inline declaration:
```yaml
#%RAML 0.8
----
external:
propertyA: valueA
propertyB: valueB
@@ -49,7 +45,6 @@ In the following example, because the original (including) file is located at *h
```yaml
#%RAML 0.8
----
#http://example-domain.org/api/example.raml
external: !include properties.raml
@@ -84,7 +84,6 @@ In the following example, the named parameter *file* can be used for sending a f
```yaml
#%RAML 0.8
----
title: Amazon simple storage API
version: 1
baseUri: https://{destinationBucket}.s3.amazonaws.com
@@ -13,7 +13,6 @@ This example shows a snippet of the RAML API definition for the GitHub v3 public
```yaml
#%RAML 0.8
----
title: GitHub API
version: v3
baseUri: https://api.github.com
@@ -64,7 +63,6 @@ The following example RAML API definition uses a Level 1 Template URI as the *ba
```yaml
#%RAML 0.8
----
title: Salesforce Chatter REST API
version: v28.0
baseUri: https://na1.salesforce.com/services/data/{version}/chatter
@@ -74,7 +72,6 @@ The following example declares an explicit base URI parameter.
```yaml
#%RAML 0.8
----
title: Amazon S3 REST API
version: 1
baseUri: https://{bucketName}.s3.amazonaws.com
@@ -89,7 +86,6 @@ A RESTful API can be reached HTTP, HTTPS, or both. The *protocols* property MAY
```yaml
#%RAML 0.8
----
title: Salesforce Chatter REST API
version: v28.0
protocols: [ HTTP, HTTPS ]
@@ -113,7 +109,6 @@ This example shows an API that accepts and returns only JSON bodies.
```yaml
#%RAML 0.8
----
title: Stormpath REST API
version: v1
baseUri: https://api.stormpath.com/{version}
@@ -126,7 +121,6 @@ To better achieve consistency and simplicity, the API definition SHOULD include
```yaml
#%RAML 0.8
----
baseUri: https://api.example.com
title: Filesystem API
version: 0.1
@@ -153,7 +147,6 @@ In addition to the reserved URI parameters described in the *baseUri* property s
```yaml
#%RAML 0.8
----
title: FreshBooks API
version: 2.1
baseUri: https://{companyName}.freshbooks.com/api/{version}/xml-in
@@ -163,7 +156,6 @@ URI parameters can be further defined by using the *uriParameters* property. The
```yaml
#%RAML 0.8
----
title: Salesforce Chatter Communities REST API
version: v28.0
baseUri: https://{communityDomain}.force.com/{communityPath}
@@ -192,7 +184,6 @@ This example shows an API definition with a single user document.
```yaml
#%RAML 0.8
----
title: ZEncoder API
baseUri: https://app.zencoder.com/api
documentation:
@@ -212,7 +203,6 @@ This example shows the same API definition (ZEncoder API), but the *documentatio
```yaml
#%RAML 0.8
----
title: ZEncoder API
baseUri: https://app.zencoder.com/api
documentation:
@@ -226,7 +216,6 @@ This example shows an RAML API definition with multiple documentation pages:
```yaml
#%RAML 0.8
----
title: GitHub API
version: v3
baseUri: https://api.github.com
@@ -8,7 +8,6 @@ This example shows an API definition with one top-level resource, /gists, and on
```yaml
#%RAML 0.8
----
title: GitHub API
version: v3
baseUri: https://api.github.com
@@ -37,7 +36,6 @@ The following example shows a top-level resource with a key */jobs* and a nested
```yaml
#%RAML 0.8
----
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
@@ -54,7 +52,6 @@ A resource MAY contain a *uriParameters* property specifying the uriParameters i
```yaml
#%RAML 0.8
----
title: GitHub API
version: v3
baseUri: https://api.github.com
@@ -74,7 +71,6 @@ If a URI parameter in a resource's relative URI is not explicitly described in a
```yaml
#%RAML 0.8
----
title: Flat Filesystem API
version: v1
/files:
@@ -87,7 +83,6 @@ A special uriParameter, *mediaTypeExtension*, is a reserved parameter. It may be
```yaml
#%RAML 0.8
----
title: API Using media type in the URL
version: v1
/users{mediaTypeExtension}:
@@ -101,13 +96,12 @@ Although URI parameters can be explicitly specified to be optional, they SHOULD
#### Base URI parameters
-A resource or a method can override a base URI template's values. This is useful to restrict or change the default or parameter selection in the base URI. The *baseUriParameters* property MAY be used to override any or all parameters defined at the root level *baseUriParameters* property, as well as base URI parameters not specified at the root level.
+A resource or a method can override a base URI template's values. This is useful to restrict or change the default or parameter selection in the base URI. The *baseUriParameters* property MAY be used to override any or all parameters defined at the root level *baseUriParameters* property, as well as base URI parameters not specified at the root level.
In the following example, calls to the /files resource must be made to "https://api-content.dropbox.com/{version}". All other calls in the API are made to "https://api.dropbox.com/{version}".
```yaml
#%RAML 0.8
----
title: Dropbox API
version: 1
baseUri: https://{apiDomain}.dropbox.com/{version}
@@ -125,6 +119,52 @@ baseUriParameters:
enum: [ "api-content" ]
```
+In a resource structure of resources and nested resources with their methods, the most specific baseUriParameter fully overrides any baseUriParameter definition made before. In the following example the resource `/user/{userId}/image` overrides the definition made in `/users`.
+
+```
+#%RAML 0.8
+title: Users API
+version: 1
+baseUri: https://{apiDomain}.someapi.com
+/users:
+ displayName: retrieve all users
+ baseUriParameters:
+ apiDomain:
+ enum: [ "api" ]
+ /{userId}/image:
+ displayName: access users pictures
+ baseUriParameters:
+ apiDomain:
+ enum: [ "static" ]
+```
+
+In the following example, the `PUT` method overrides the definition made in `/user/{userId}/image`.
+
+```
+#%RAML 0.8
+title: Users API
+version: 1
+baseUri: https://{apiDomain}.someapi.com
+/users:
+ displayName: retrieve all users
+ baseUriParameters:
+ apiDomain:
+ enum: [ "api" ]
+ /{userId}/image:
+ displayName: access users pictures
+ baseUriParameters:
+ apiDomain:
+ enum: [ "static" ]
+ get:
+ displayName: retrieve a user's picture
+ put:
+ displayName: update a user's picture
+ baseUriParameters:
+ apiDomain:
+ enum: [ "content-update" ]
+
+```
+
The special baseUriParameter *version* is reserved; processing applications MUST replace occurrences of {version} in any baseUri property values with the value of the root-level *version* property. The {version} parameter, if used in a baseUri, is required: if it is ued in a baseUri, the *version* root-level property MUST be provided and MUST be a valid non-empty URI fragment.
#### Absolute URI
@@ -149,7 +189,6 @@ In this example, /user is a top-level resource that has no children; /users is a
```yaml
#%RAML 0.8
----
title: GitHub API
version: v3
baseUri: https://api.github.com
@@ -192,7 +231,6 @@ This example shows a resource, /jobs, with POST and GET methods (verbs) declared
```yaml
#%RAML 0.8
----
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
@@ -207,7 +245,6 @@ The value of the *description* property MAY be formatted using Markdown [MARKDOW
```yaml
#%RAML 0.8
----
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
@@ -236,7 +273,6 @@ This example shows a POST method with an HTTP header.
```yaml
#%RAML 0.8
----
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
@@ -254,7 +290,6 @@ In the following example, the header x-metadata-{*} is used to send metadata tha
```yaml
#%RAML 0.8
----
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
@@ -278,7 +313,6 @@ Documentation generators MUST include content specified as example information f
```yaml
#%RAML 0.8
----
title: ZEncoder API
version: v2
baseUri: https://app.zencoder.com/api/{version}
@@ -306,7 +340,6 @@ In the following example, the GET method is accessible through both HTTP and HTT
```yaml
#%RAML 0.8
----
title: Twitter API
version: 1.1
baseUri: https://api.twitter.com/{version}
@@ -325,7 +358,6 @@ The *queryParameters* property is a map in which the key is the query parameter'
```yaml
#%RAML 0.8
----
title: GitHub API
version: v3
baseUri: https://api.github.com
@@ -345,7 +377,6 @@ Query string *queryParameters* properties MAY include an *example* attribute. Do
```yaml
#%RAML 0.8
----
title: GitHub API
version: v3
baseUri: https://api.github.com/{version}
@@ -400,7 +431,6 @@ Documentation generators MUST use *form* properties' *example* attributes to gen
```yaml
#%RAML 0.8
----
title: Twilio API
version: 2010-04-01
baseUri: https://api.twilio.com/{version}
@@ -20,7 +20,6 @@ The *resourceTypes* and *traits* properties are declared at the API definition's
```yaml
#%RAML 0.8
----
title: Example API
version: v1
resourceTypes:
@@ -47,7 +46,6 @@ The following example builds on the previous one, but the the resource types and
```yaml
#%RAML 0.8
----
title: Example API
version: v1
resourceTypes:
@@ -74,7 +72,6 @@ Collections of resourceTypes may also be combined, as can collections of traits.
```yaml
#%RAML 0.8
----
title: Example API
version: v1
resourceTypes:
@@ -116,7 +113,6 @@ To apply functions, append them to the parameter name within the double angle br
```yaml
#%RAML 0.8
----
title: Example API
version: v1
mediaType: application/json
@@ -162,7 +158,6 @@ The following example shows an optional *post?* property that defines a body par
```yaml
#%RAML 0.8
----
title: Example of Optional Properties
resourceTypes:
- auditableResource
@@ -193,7 +188,6 @@ A trait may also be applied to a resource by using the *is* key, which is equiva
```yaml
#%RAML 0.8
----
title: Example API
version: v1
resourceTypes:
@@ -214,7 +208,6 @@ To pass parameter values to resource types and traits, use a map when declaring
```yaml
#%RAML 0.8
----
title: Example API
version: v1
resourceTypes:
Oops, something went wrong.

0 comments on commit 01f9c1f

Please sign in to comment.