petail 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90ccb34a36bfc17201ce4b4881e8f37acbbc3714f076c5de0e7cf1d5ad373346
-  data.tar.gz: 0a2ee99b2cd3191aa9ec08473a218436bd259576f3b0e6e31c8779eddcbfe5b0
+  metadata.gz: 417bd45430e7d40be79470dcd1a09f6fbab6ca729a893c02568f944b67592cd5
+  data.tar.gz: 328809222adc5db346e50b7b144a98c3fd4c0f6e32fef701ee03f7d65a33b210
 SHA512:
-  metadata.gz: b663a7f90af61259298cd14a8f23c63afbd0d0e6aab80c3c38c0242e7cc240418563021623bcf95e7af88e3368788bdad8ac30178431788f4cc3e552219815b7
-  data.tar.gz: 6efc822522e3e828df9c2d81953a8b2a2344e6ec9aec462ebe063cb32feffcc10552b4f874b67888d3e347875a805621df317b429d2a57227ecb55e061530611
+  metadata.gz: c01be4f0f48a6b5f9b4622b8f133102a8cc0abe073c9176827748b8848f1208c7682590fd52ae0734a696e6cd2fa3d5beb7fc338fc520bc7afaef9cb55eb9a9c
+  data.tar.gz: 1c684b3c8e69e3a9c54b627226e2c3ebdecafe1cf013b70f69ac0c6582a5ff4394e201ece321eee3e1115b7fa8573e7d234edc97e20c5b609a770b05cdcc7fad

data/README.adoc

@@ -181,7 +181,7 @@ Both serialization and deserialization of JSON is supported. For example, given
 [source,ruby]
 ----
 payload = Petail[
-  type: "https://test.io/problem_details/out_of_credit",
+  type: "https://demo.io/problem_details/out_of_credit",
   title: "You do not have enough credit.",
   status: 403,
   detail: "Your current balance is 30, but that costs 50.",
@@ -198,11 +198,11 @@ This means you can serialize as follows:
 [source,ruby]
 ----
 payload.to_json
-# "{\"type\":\"https://test.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
+# "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
 
 payload.to_json indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"
 # {
-#   "type": "https://test.io/problem_details/out_of_credit",
+#   "type": "https://demo.io/problem_details/out_of_credit",
 #   "title": "You do not have enough credit.",
 #   "status": 403,
 #   "detail": "Your current balance is 30, but that costs 50.",
@@ -221,7 +221,7 @@ You can also deserialize by taking the result of the above and turning the raw J
 
 [source,ruby]
 ----
-Petail.from_json "{\"type\":\"https://test.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
+Petail.from_json "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
 
 # #<Struct:Petail::Payload:0x00007670
 #   detail = "Your current balance is 30, but that costs 50.",
@@ -235,7 +235,7 @@ Petail.from_json "{\"type\":\"https://test.io/problem_details/out_of_credit\",\"
 #   instance = "/accounts/1",
 #   status = 403,
 #   title = "You do not have enough credit.",
-#   type = "https://test.io/problem_details/out_of_credit"
+#   type = "https://demo.io/problem_details/out_of_credit"
 # >
 ----
 
@@ -246,7 +246,7 @@ XML is supported too but isn't as robust as JSON support, at the moment. This is
 [source,ruby]
 ----
 payload = Petail[
-  type: "https://test.io/problem_details/out_of_credit",
+  type: "https://demo.io/problem_details/out_of_credit",
   title: "You do not have enough credit.",
   status: 403,
   detail: "Your current balance is 30, but that costs 50.",
@@ -263,13 +263,13 @@ This means you can serialize as follows:
 [source,ruby]
 ----
 payload.to_xml
-# "<?xml version='1.0' encoding='UTF-8'?><problem xmlns='urn:ietf:rfc:7807'><type>https://test.io/problem_details/out_of_credit</type><title>You do not have enough credit.</title><status>403</status><detail>Your current balance is 30, but that costs 50.</detail><instance>/accounts/1</instance><balance>30</balance><accounts><i>/accounts/1</i><i>/accounts/10</i></accounts></problem>"
+# "<?xml version='1.0' encoding='UTF-8'?><problem xmlns='urn:ietf:rfc:7807'><type>https://demo.io/problem_details/out_of_credit</type><title>You do not have enough credit.</title><status>403</status><detail>Your current balance is 30, but that costs 50.</detail><instance>/accounts/1</instance><balance>30</balance><accounts><i>/accounts/1</i><i>/accounts/10</i></accounts></problem>"
 
 payload.to_xml indent: 2
 # <?xml version='1.0' encoding='UTF-8'?>
 # <problem xmlns='urn:ietf:rfc:7807'>
 #   <type>
-#     https://test.io/problem_details/out_of_credit
+#     https://demo.io/problem_details/out_of_credit
 #   </type>
 #   <title>
 #     You do not have enough credit.
@@ -306,7 +306,7 @@ You can also deserialize by taking the result of the above and turning the raw J
 payload = Petail.from_xml <<~XML
   <?xml version='1.0' encoding='UTF-8'?>
   <problem xmlns='urn:ietf:rfc:7807'>
-    <type>https://test.io/problem_details/out_of_credit</type>
+    <type>https://demo.io/problem_details/out_of_credit</type>
     <title>You do not have enough credit.</title>
     <status>403</status>
     <detail>Your current balance is 30, but that costs 50.</detail>
@@ -331,10 +331,75 @@ XML
 #   instance = "/accounts/1",
 #   status = 403,
 #   title = "You do not have enough credit.",
-#   type = "https://test.io/problem_details/out_of_credit"
+#   type = "https://demo.io/problem_details/out_of_credit"
 # >
 ----
 
+=== Examples
+
+There is a lot of useful information you can provide in your problem details depending on the context you are working in. Some have been shown above but here's a few more that might be of interest.
+
+==== HATEOAS
+
+With link:https://nordicapis.com/tools-to-make-hateoas-compliance-easier[HATEOAS], you can provide additional information and links for which the client can understand what next actions are available. The below example shows how you can provide additional resources for clients to adjust accordingly:
+
+[source,ruby]
+----
+Petail[
+  type: "https://demo.io/problem_details/rate_limit",
+  title: "Rate limit exceeded",
+  status: 429,
+  detail: "You have exceeded your rate limit of 150 requests per minute",
+  instance: "/articles",
+  extensions: {
+    retry_after: 5,
+    links: [
+      {
+        ref: "self",
+        href: "/articles"
+      },
+      {
+        rel: "retry",
+        href: "/articles",
+        title: "Retry after five minutes"
+      },
+      {
+        rel: "status",
+        href: "/statuses/rate_limit",
+        title: "Check current rate limit usage"
+      }
+    ]
+  }
+]
+----
+
+==== Semantic Structure
+
+In other situations, you might need a different structure in order to aid clients that might be AI driven which needs a semantically structured response in order to course correct. Example:
+
+[source,ruby]
+----
+Petail[
+  type: "https://demo.io/problem_details/invalid_field",
+  title: "Invalid field value",
+  status: 400,
+  detail: "The category requested doesn't exist",
+  instance: "/categories",
+  extensions: {
+    parameters: {
+      category_id: 123
+    },
+    suggestions: [
+      "ruby",
+      "git",
+      "htmx"
+    ]
+  }
+]
+----
+
+With the above, the client now knows what parameters where invalid along with relevant suggestions for proceeding. Even better, the suggestions implicitly show the types of IDs that are required.
+
 == Development
 
 To contribute, run:

data/petail.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "petail"
-  spec.version = "0.4.0"
+  spec.version = "0.5.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/petail"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: petail
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -109,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A RFC 9457 Problem Details for HTTP APIs implementation.
 test_files: []