added a data wrapper and links

bump-sh-examples · Feb 2, 2024 · 5d5a38b · 5d5a38b
1 parent 702f9ed
commit 5d5a38b
Show file tree

Hide file tree

Showing 17 changed files with 150 additions and 65 deletions.
diff --git a/.spectral.yaml b/.spectral.yaml
@@ -5,3 +5,6 @@ extends:
 
 rules:
   operation-tags: false
+  owasp:api4:2019-array-limit: false
+  owasp:api4:2019-string-limit: false
+  owasp:api4:2019-string-restricted: false
diff --git a/components/headers/RateLimit.yaml b/components/headers/RateLimit.yaml
@@ -0,0 +1,8 @@
+description: | 
+  The RateLimit header is communicate quota policies, and contains a `limit` to
+  conveys the expiring limit, `remaining` to convey the remaining quota units,
+  and `reset` to convey the time window reset time.
+schema:
+  type: string
+  examples:
+   - limit=10, remaining=0, reset=10
diff --git a/components/headers/Retry-After.yaml b/components/headers/Retry-After.yaml
@@ -0,0 +1,14 @@
+description: | 
+  The Retry-After header indicates how long the user agent should wait before making a follow-up request. 
+  The value is in seconds and can be an integer or a date in the future. 
+  If the value is an integer, it indicates the number of seconds to wait. 
+  If the value is a date, it indicates the time at which the user agent should make a follow-up request. 
+schema:
+  type: string
+examples:
+  integer:
+    value: '120'
+    summary: Retry after 120 seconds
+  date:
+    value: 'Fri, 31 Dec 2021 23:59:59 GMT'
+    summary: Retry after the specified date
diff --git a/components/responses/BadRequest.yaml b/components/responses/BadRequest.yaml
@@ -1,4 +1,7 @@
 description: Bad Request
+headers:
+  RateLimit: 
+    $ref: ../headers/RateLimit.yaml
 content:
   application/problem+json:
     example:

diff --git a/components/responses/Conflict.yaml b/components/responses/Conflict.yaml
@@ -1,4 +1,7 @@
 description: Conflict
+headers:
+  RateLimit: 
+    $ref: ../headers/RateLimit.yaml
 content:
   application/problem+json:
     example:

diff --git a/components/responses/Forbidden.yaml b/components/responses/Forbidden.yaml
@@ -1,4 +1,7 @@
 description: Forbidden
+headers:
+  RateLimit: 
+    $ref: ../headers/RateLimit.yaml
 content:
   application/problem+json:
     example:

diff --git a/components/responses/InternalServerError.yaml b/components/responses/InternalServerError.yaml
@@ -1,4 +1,7 @@
 description: Internal Server Error
+headers:
+  RateLimit: 
+    $ref: ../headers/RateLimit.yaml
 content:
   application/problem+json:
     example:

diff --git a/components/responses/NotFound.yaml b/components/responses/NotFound.yaml
@@ -1,4 +1,7 @@
 description: Not Found
+headers:
+  RateLimit: 
+    $ref: ../headers/RateLimit.yaml
 content:
   application/problem+json:
     example:

diff --git a/components/responses/TooManyRequests.yaml b/components/responses/TooManyRequests.yaml
@@ -1,4 +1,9 @@
 description: Too Many Requests
+headers:
+  RateLimit: 
+    $ref: ../headers/RateLimit.yaml
+  Retry-After: 
+    $ref: ../headers/Retry-After.yaml
 content:
   application/problem+json:
     example:

diff --git a/components/responses/Unauthorized.yaml b/components/responses/Unauthorized.yaml
@@ -1,4 +1,7 @@
 description: Unauthorized
+headers:
+  RateLimit: 
+    $ref: ../headers/RateLimit.yaml
 content:
   application/problem+json:
     example:

diff --git a/components/schemas/Links-Pagination.yaml b/components/schemas/Links-Pagination.yaml
@@ -0,0 +1,8 @@
+type: object
+properties:
+  next:
+    type: string
+    format: uri
+  prev:
+    type: string
+    format: uri
diff --git a/components/schemas/Links-Self.yaml b/components/schemas/Links-Self.yaml
@@ -0,0 +1,5 @@
+type: object
+properties:
+  self:
+    type: string
+    format: uri
diff --git a/components/schemas/Links.yaml b/components/schemas/Links.yaml
@@ -0,0 +1,4 @@
+type: object
+properties:
+  links:
+    type: object
diff --git a/components/schemas/Wrapper.yaml b/components/schemas/Wrapper.yaml
@@ -0,0 +1,25 @@
+$id: Wrapper
+description: This is a generic request/response wrapper which contains both data and links which serve as hypermedia controls (HATEOAS).
+type: object
+properties:
+  data:
+    description: The actual data, which can be either an object or an array of objects.
+    oneOf:
+      - type: object 
+      - type: array
+        items:
+          type: object
+  links:
+    description: A set of hypermedia links which serve as controls for the client.
+    type: object
+    readOnly: true
+    properties:
+      self:
+        type: string
+        format: uri
+      next:
+        type: string
+        format: uri
+      prev:
+        type: string
+        format: uri
diff --git a/paths/bookings.yaml b/paths/bookings.yaml
@@ -8,24 +8,17 @@ get:
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              data:
-                type: array
-                items:
-                  $ref: ../components/schemas/Booking.yaml
-              links:
-                type: object
-                properties:
-                  self:
-                    type: string
-                    format: uri
-                  next:
-                    type: string
-                    format: uri
-                  prev:
-                    type: string
-                    format: uri
+            allOf:
+              - $ref: ../components/schemas/Wrapper.yaml 
+              - data:
+                  type: array
+                  items:
+                    $ref: ../components/schemas/Booking.yaml
+              - links:
+                  allOf: 
+                    - $ref: ../components/schemas/Links.yaml
+                    - $ref: ../components/schemas/Links-Self.yaml
+                    - $ref: ../components/schemas/Links-Pagination.yaml
           example:
             data:
               - booking_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
@@ -38,6 +31,11 @@ get:
                 passenger_name: Jane Smith
                 has_bicycle: false
                 has_dog: false
+            links:
+              self: https://api.example.com/bookings
+              next: https://api.example.com/bookings?page=2
+    '400':
+      $ref: ../components/responses/BadRequest.yaml
     '401':
       $ref: ../components/responses/Unauthorized.yaml
     '403':
@@ -58,16 +56,12 @@ post:
     content:
       application/json:
         schema:
-          type: object
-          properties:
-            data:
-              $ref: ../components/schemas/Booking.yaml
-            links:
-              type: object
-              properties:
-                self:
-                  type: string
-                  format: uri
+          allOf: 
+            - $ref: ../components/schemas/Wrapper.yaml
+            - data:
+                type: array
+                items:
+                  $ref: ../components/schemas/Trip.yaml
         example:
           data:
             trip_id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
@@ -80,7 +74,14 @@ post:
       content:
         application/json:
           schema:
-            $ref: ../components/schemas/Booking.yaml
+            allOf: 
+              - $ref: ../components/schemas/Wrapper.yaml
+              - data:
+                  $ref: ../components/schemas/Booking.yaml
+              - links:
+                  allOf:
+                    - $ref: ../components/schemas/Links.yaml
+                    - $ref: ../components/schemas/Links-Self.yaml
     '400':
       $ref: ../components/responses/BadRequest.yaml
     '401':

diff --git a/paths/stations.yaml b/paths/stations.yaml
@@ -8,24 +8,17 @@ get:
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              data:
-                type: array
-                items:
-                  $ref: ../components/schemas/Station.yaml
-              links:
-                type: object
-                properties:
-                  self:
-                    type: string
-                    format: uri
-                  next:
-                    type: string
-                    format: uri
-                  prev:
-                    type: string
-                    format: uri
+            allOf: 
+              - $ref: ../components/schemas/Wrapper.yaml
+              - data:
+                  type: array
+                  items:
+                    $ref: ../components/schemas/Station.yaml
+              - links:
+                  allOf:
+                    - $ref: ../components/schemas/Links.yaml
+                    - $ref: ../components/schemas/Links-Self.yaml
+                    - $ref: ../components/schemas/Links-Pagination.yaml
           example:
             data:
               - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
@@ -36,6 +29,11 @@ get:
                 name: Paris Gare du Nord
                 address: 18 Rue de Dunkerque 75010 Paris, France
                 country_code: FR
+            links:
+              self: https://api.example.com/stations
+              next: https://api.example.com/stations?page=2
+    '400':
+      $ref: ../components/responses/BadRequest.yaml
     '401':
       $ref: ../components/responses/Unauthorized.yaml
     '403':

diff --git a/paths/trips.yaml b/paths/trips.yaml
@@ -45,24 +45,17 @@ get:
       content:
         application/json:
           schema:
-            type: object
-            properties:
-              data:
-                type: array
-                items:
-                  $ref: ../components/schemas/Trip.yaml
-              links:
-                type: object
-                properties:
-                  self:
-                    type: string
-                    format: uri
-                  next:
-                    type: string
-                    format: uri
-                  prev:
-                    type: string
-                    format: uri
+            allOf: 
+              - $ref: ../components/schemas/Wrapper.yaml
+              - data:
+                  type: array
+                  items:
+                    $ref: ../components/schemas/Trip.yaml
+              - links:
+                  allOf: 
+                    - $ref: ../components/schemas/Links.yaml
+                    - $ref: ../components/schemas/Links-Self.yaml
+                    - $ref: ../components/schemas/Links-Pagination.yaml
           example:
             data:
               - id: efdbb9d1-02c2-4bc3-afb7-6788d8782b1e
@@ -73,6 +66,9 @@ get:
                 price: 50
                 bicycles_allowed: true
                 dogs_allowed: true
+            links:
+              self: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&date=2024-02-01
+              next: https://api.example.com/trips?origin=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&destination=efdbb9d1-02c2-4bc3-afb7-6788d8782b1e&date=2024-02-01&page=2
     '401':
       $ref: ../components/responses/Unauthorized.yaml
     '403':