Merge pull request #13 from adidas/hal-examples-and-snippets

HAL snippets and packages

rest-api-guidelines/functionality/message/HAL-snippet-full-OpenApi3.yaml

@@ -0,0 +1,81 @@
+openapi: 3.0.0
+info:
+  title: HAL
+  description: 'HAL snippet for OAS3'
+  contact:
+    name: Andrzej Jarzyna
+    url: https://github.com/jerzyn
+    email: andrzej.jarzyna@adidas.com
+  version: '1.0.0'
+servers:
+- url: http://{defaultHost}
+  variables:
+    defaultHost:
+      default: www.example.com
+paths: {}
+components:
+  schemas:
+    HALLinkObject:
+      title: HALLinkObject
+      required:
+      - href
+      type: object
+      properties:
+        href:
+          type: string
+        templated:
+          type: boolean
+        type:
+          type: string
+        deprecation:
+          type: string
+        name:
+          type: string
+        profile:
+          type: string
+        title:
+          type: string
+        hreflang:
+          type: string
+    HALCuriesLink:
+      title: HALCuriesLink
+      required:
+      - templated
+      - href
+      type: object
+      properties:
+        templated:
+          type: string
+          example: True
+        href:
+          type: string
+        type:
+          type: string
+        deprecation:
+          type: string
+        name:
+          type: string
+        profile:
+          type: string
+        title:
+          type: string
+        hreflang:
+          type: string
+    HAL:
+      title: HAL
+      type: object
+      properties:
+        _links:
+          $ref: '#/components/schemas/Links'
+        _embedded:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/HAL'
+      description: JSON Hypertext Application Language. Definition of [HAL message format](https://tools.ietf.org/html/draft-kelly-json-hal-08)
+    Links:
+      title: Links
+      type: object
+      properties:
+        curies:
+          $ref: '#/components/schemas/HALCuriesLink'
+tags: []

rest-api-guidelines/functionality/message/HAL-snippet.yaml

@@ -0,0 +1,74 @@
+swagger: "2.0"
+info:
+  title: HAL
+  description: HAL snippet for OAS2
+  version: 1.0.0
+host: api.example.com
+basePath: /v1
+schemes:
+  - https
+paths: {}
+definitions: 
+  HalLinkObject:
+    title: HAL Link Object
+    type: object
+    properties:
+      href:
+        type: string
+      templated:
+        type: boolean
+      type:
+        type: string
+      deprecation:
+        type: string
+      name:
+        type: string
+      profile:
+        type: string
+      title:
+        type: string
+      hreflang:
+        type: string
+    required:
+      - href
+  HalCuriesLink:
+    title: HAL Curies Link
+    allOf:
+      - type: object
+        properties:
+          templated:
+            enum:
+              - true
+        required:
+          - templated
+      - $ref: '#/definitions/HalLinkObject'
+  HAL:
+    title: HAL
+    description: >-
+      JSON Hypertext Application Language. Definition of [HAL message
+      format](https://tools.ietf.org/html/draft-kelly-json-hal-08)
+    type: object
+    properties:
+      _links:
+        type: object
+        additionalProperties:
+          allOf:
+            - $ref: '#/definitions/HalLinkObject'
+            - type: array
+              items:
+                $ref: '#/definitions/HalLinkObject'
+        properties:
+          curies:
+            allOf:
+              - $ref: '#/definitions/HalCuriesLink'
+              - type: array
+                items:
+                  $ref: '#/definitions/HalCuriesLink'
+      _embedded:
+        type: object
+        additionalProperties:
+          allOf:
+            - $ref: '#/definitions/HAL'
+            - type: array
+              items:
+                $ref: '#/definitions/HAL'

rest-api-guidelines/functionality/message/hal.md

@@ -8,6 +8,12 @@ The [`application/hal+json`](http://stateless.co/hal_specification.html) \(HAL\)
 
 This document is an informal introduction to the HAL media type. For more details see [HAL - Hypertext Application Language Specification](http://stateless.co/hal_specification.html).
 
+## HAL Document Object Model
+
+HAL document follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL).
+
+YAML code snippets are provided for [OpenAPI Specification 2.0/Swagger](./HAL-snippet.yaml) and [OpenAPI Specification 3.x](./HAL-snippet-full-OpenApi3.yaml).
+
 ## Simple Document Example
 
 The simplest Hal document looks like an empty JSON \(it is an empty JSON!\):
@@ -113,7 +119,8 @@ Some APIs using HAL:
 
 Refer to the [extensive list of libraries that work with HAL](https://github.com/mikekelly/hal_specification/wiki/Libraries).
 
+For working with HAL and Node.js using [HALson npm package](https://www.npmjs.com/package/halson) is suggested.
+
 ### Spring Framework
 
-Spring framework supports HAL out of the box. More info can be found in [Spring Documentation](https://spring.io/guides/gs/rest-hateoas/) and [examples](https://github.com/spring-guides/gs-rest-hateoas).
-
+Spring framework supports HAL out of the box. More info can be found in [Spring Documentation](https://spring.io/guides/gs/rest-hateoas/) and [examples](https://github.com/spring-guides/gs-rest-hateoas).