Callback review and preliminary message expression syntax #891

darrelmiller · 2017-02-17T22:22:03Z

No description provided.

…dm/callback-review

DavidBiesack · 2017-02-20T18:35:36Z

versions/3.0.md

@@ -1555,15 +1555,70 @@ description: object created

 #### <a name="callbackObject"></a>Callback Object

-A container for possible out-of band callbacks from an operation. A callback may be returned from an operation, calling back to the path specified in the operation object.
+A map of possible out-of band callbacks related to the parent operation. Each value in the map is an [operation object](#operationObject) that describes a request that may be initiated by the API provider and the responses expected. The key value used to identify callback object is an expression, that when evaluated at runtime, identifies a URL to used for the callback operation.


add article "the" : "used to identify the callback object"

suggested: "is an expression, evaluated at runtime, that identifies... "

DavidBiesack · 2017-02-20T18:38:58Z

versions/3.0.md

@@ -1555,15 +1555,70 @@ description: object created

 #### <a name="callbackObject"></a>Callback Object

-A container for possible out-of band callbacks from an operation. A callback may be returned from an operation, calling back to the path specified in the operation object.
+A map of possible out-of band callbacks related to the parent operation. Each value in the map is an [operation object](#operationObject) that describes a request that may be initiated by the API provider and the responses expected. The key value used to identify callback object is an expression, that when evaluated at runtime, identifies a URL to used for the callback operation.

 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---


I believe CommonMark does not support tables with this notation; one must use HTML <table> elements.

:-) I realize this might sound a little hypocritical but we are suggesting CommonMark in OpenAPI definitions, but we are still using GFM in the spec.

DavidBiesack · 2017-02-20T18:39:58Z

versions/3.0.md


 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="responseName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback payload structure
+<a name="responseName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback request and expected responses


name="callbackName" perhaps?

DavidBiesack · 2017-02-20T18:42:13Z

versions/3.0.md


 This object can be extended with [Specification Extensions](#specificationExtensions). 

+##### Key Expression
+
+The key used to identify the callback object is also an expression that can be evaluated on the runtime HTTP request/response to identify the URL to be used for the callback request.  A simple example might be "$request.body.url".  However, the expression syntax enables accessing the complete HTTP message and reaching into any payload that can map to an object/array/property data model. 


"evaluated in the context of a runtime HTTP request/response" (It's not clear what "evaluated on the runtime HTTP request/response object means" since those are not executable, but they do provide a context for expression evaluation.

Fixed. Thanks!

DavidBiesack · 2017-02-20T18:55:05Z

versions/3.0.md

+
+The key used to identify the callback object is also an expression that can be evaluated on the runtime HTTP request/response to identify the URL to be used for the callback request.  A simple example might be "$request.body.url".  However, the expression syntax enables accessing the complete HTTP message and reaching into any payload that can map to an object/array/property data model. 
+
+The expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax


Did you consider using JSON Pointer or JSONPath for the body-reference expressions? In particular, when extracting elements from arrays, it is often necessary to pass in predicates/filters to match a specific array elements. (I'm extrapolating based on from experience with UnRAVL which also allows extracting data from response bodies.)

I had not considered using those for just the body-reference. I had ruled out using them for the complete expression, but using it for just the body-reference is quite an cool idea. I'd like to use JSON Pointer because we already need that in tooling to support $refs.

I have a fairly significant update to this PR because I found it contradicted some of the docs in Links which I am also reviewing. I'll post an update soon and I'll see if it is easy to incorporate JSONPointer. Nice thing about that is approach is in the future we could open the door to using other fragment syntaxes for other media types where JSONPointer is not appropriate.

I'm not sure about the predicates/filters, I do see the value but it adds quite a bit of work for tooling. I'm not going to include anything for the moment, but I'll bring it up with the TDC tomorrow.

DavidBiesack · 2017-02-20T18:57:04Z

versions/3.0.md

+$request.header.content-Type | application/json
+$request.body.failed | http://clientdomain.com/stillrunning
+$request.body.successurls[2] | http://clientdomain.com/medium
+$response.header.Location | http://example.org/subscription/1


This expression notation may need some mechanism to provide a default value if the item is not found, i.e. $request.body.successurls[2] | $response.header.Location
would return the second successurl if it exists, or the location header.

In the Links section, the suggestion is that if the item is not found, then the value is null. I'm not exactly sure what we do if the reference points to something that is not a primitive.

DavidBiesack · 2017-02-20T18:57:34Z

versions/3.0.md

+      query-reference = "query." name  
+      path-reference = "path." name
+      body-reference = "body" *( index | "." name )
+      index = "[" *(digit) "]"


document is indexing is zero-based (I assume, recommend) or 1-based.

If we move to JSONPointer, I can punt on this :-)

darrelmiller · 2017-02-20T19:44:56Z

@DavidBiesack Huge thanks for the feedback. I've made most of the fixes. Updated PR coming soon.

darrelmiller · 2017-02-20T20:58:53Z

This latest update has a number of changes to the variable expressions used for both callbacks and links.

It was necessary to add syntax to access parameters using $request.path.{name} $request.query.{name} and $request.header.{name} since the parameter names are only unique in a single location.

Also, instead of creating a new syntax for reaching into request and response bodies, this proposal suggests using a JSON Pointer for accessing the body instead:
e.g.

 $response.body(/id)

Another alternative syntax would be

$response.body#/id

But I'm tending to prefer the function style over the fragment

earth2marsh · 2017-02-21T17:08:56Z

versions/3.0.md

+Content-Length: 123
+
+{
+  "failedurl" : "http://clientdomain.com/failed"


Suggest failedUrl and successUrls (camel)

I like the $response.body#/id variant.

whitlockjc · 2017-02-21T22:31:57Z

fehguy · 2017-02-21T22:39:19Z

Well that's a fun read! Looks good to me, you have my 👍

webron

Added some cosmetic changes.

webron · 2017-02-22T04:28:24Z

versions/3.0.md


-A container for possible out-of band callbacks from an operation. A callback may be returned from an operation, calling back to the path specified in the operation object.
+A map of possible out-of band callbacks related to the parent operation.
+Each value in the map is an [operation object](#operationObject) that describes a request that may be initiated by the API provider and the expected responses.


We can fix it later, but should be Operation Object

webron · 2017-02-22T04:29:37Z

versions/3.0.md

+The key used to identify the callback object is a variable expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.
+A simple example might be `$request.body#/url`.
+However, using [variable substition](#variableSubstition) syntax the complete HTTP message can be accessed.
+This includes accessing any part of a body that can be accessed using a JSONPointer [RFC6901](https://tools.ietf.org/html/rfc6901). 


JSON Pointer

webron · 2017-02-22T04:31:46Z

versions/3.0.md

-description | string | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
+href        | `string`    | a relative or absolute URL to a linked resource. This field is mutually exclusive with the `operationId` field.
+operationId | `string` | the name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive with the `href` field.  Relative `href` values _may_ be used to locate an existing Operation Object in the OAS.
+parameters  | [Link Parameters Object](#linkParameters) | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.


Parameters Object instead of Link Parameters Object

I stand corrected!

webron · 2017-02-22T04:37:35Z

👍

I was going to say something about headers being case insensitive but you got it!

Does it make sense to support cookies too in variable substitution? (#probablynot #pleasedontkillme)

…dm/callback-review

Callback review and preliminary message expression syntax

darrelmiller added 2 commits February 17, 2017 17:18

Callback review and preliminary message expression syntax

6e6c4f6

Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into …

fcc6c66

…dm/callback-review

DavidBiesack reviewed Feb 20, 2017

View reviewed changes

Updates to align links and callbacks

4197f43

darrelmiller mentioned this pull request Feb 21, 2017

3.0md callback responses? #896

Closed

darrelmiller added 2 commits February 20, 2017 22:06

Fixed property name of callbacks

4068d00

Fixed callback example

bc9da31

earth2marsh reviewed Feb 21, 2017

View reviewed changes

darrelmiller added 2 commits February 21, 2017 17:20

Updates to Callback/Links based on meeting

b268c06

Almost missed Marsh's comment.

17fdf10

webron reviewed Feb 22, 2017

View reviewed changes

darrelmiller added 2 commits February 22, 2017 13:25

Fixing spaces and capitals for Ron

9e6f586

Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into …

d4e2cfe

…dm/callback-review

darrelmiller merged commit 4d322ec into OpenAPI.next Feb 22, 2017

darrelmiller deleted the dm/callback-review branch February 22, 2017 18:29

AndersDJohnson pushed a commit to AndersDJohnson/OpenAPI-Specification that referenced this pull request Apr 8, 2019

Merge pull request OAI#891 from OAI/dm/callback-review

f790e8d

Callback review and preliminary message expression syntax

phillip mentioned this pull request Mar 25, 2024

[Snyk] Security upgrade markdown-it from 12.3.2 to 13.0.2 goshippo/OpenAPI-Specification#6

Open

VeracodeVince mentioned this pull request Mar 25, 2024

[Snyk] Security upgrade markdown-it from 12.3.2 to 13.0.2 VeracodeVince/OpenAPI-Specification#1

Open

Yazanurah mentioned this pull request Mar 25, 2024

[Snyk] Security upgrade markdown-it from 12.3.2 to 13.0.2 Yazanurah/OpenAPI-Specification#1

Merged

BitcoinOutput mentioned this pull request Mar 25, 2024

[Snyk] Security upgrade markdown-it from 12.3.2 to 13.0.2 BitcoinOutput/OpenAPI-Specification#2

Open

hknysfhera mentioned this pull request Mar 26, 2024

[Snyk] Security upgrade markdown-it from 12.3.2 to 13.0.2 hknysfhera/OpenAPI-Specification#1

Open

Redwoodtj mentioned this pull request Mar 26, 2024

[Snyk] Security upgrade markdown-it from 12.3.2 to 13.0.2 Redwoodtj/OpenAPI-Specification#2

Open

Manny27nyc mentioned this pull request Mar 27, 2024

[Snyk] Security upgrade markdown-it from 12.3.2 to 13.0.2 Manny27nyc/OpenAPI-Specification#7

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Callback review and preliminary message expression syntax #891

Callback review and preliminary message expression syntax #891

darrelmiller commented Feb 17, 2017

DavidBiesack Feb 20, 2017 •

edited

Loading

DavidBiesack Feb 20, 2017 •

edited

Loading

darrelmiller Feb 20, 2017

DavidBiesack Feb 20, 2017 •

edited

Loading

darrelmiller Feb 20, 2017

DavidBiesack Feb 20, 2017

darrelmiller Feb 20, 2017

DavidBiesack Feb 20, 2017

darrelmiller Feb 20, 2017

DavidBiesack Feb 20, 2017

darrelmiller Feb 20, 2017

darrelmiller Feb 20, 2017

DavidBiesack Feb 20, 2017

darrelmiller Feb 20, 2017

DavidBiesack Feb 20, 2017

darrelmiller Feb 20, 2017

darrelmiller commented Feb 20, 2017

darrelmiller commented Feb 20, 2017 •

edited

Loading

earth2marsh Feb 21, 2017

whitlockjc Feb 21, 2017

whitlockjc commented Feb 21, 2017

fehguy commented Feb 21, 2017

webron left a comment

webron Feb 22, 2017

webron Feb 22, 2017

webron Feb 22, 2017

webron Feb 22, 2017

webron commented Feb 22, 2017


		The key used to identify the callback object is also an expression that can be evaluated on the runtime HTTP request/response to identify the URL to be used for the callback request. A simple example might be "$request.body.url". However, the expression syntax enables accessing the complete HTTP message and reaching into any payload that can map to an object/array/property data model.

		The expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax

Callback review and preliminary message expression syntax #891

Callback review and preliminary message expression syntax #891

Conversation

darrelmiller commented Feb 17, 2017

DavidBiesack Feb 20, 2017 • edited Loading

Choose a reason for hiding this comment

DavidBiesack Feb 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DavidBiesack Feb 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

darrelmiller commented Feb 20, 2017

darrelmiller commented Feb 20, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whitlockjc commented Feb 21, 2017

fehguy commented Feb 21, 2017

webron left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webron commented Feb 22, 2017

DavidBiesack Feb 20, 2017 •

edited

Loading

DavidBiesack Feb 20, 2017 •

edited

Loading

DavidBiesack Feb 20, 2017 •

edited

Loading

darrelmiller commented Feb 20, 2017 •

edited

Loading