Skip to content

edit Response Payload Example #1187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

edit Response Payload Example #1187

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2046,15 +2046,15 @@ ColorSelection:

Would produce three links with the `colorName` of `red`, `green`, and `blue`:

As with all links, it is at the clients' discretion to follow them, neither
permissions nor the ability to make a successful call to that link is guaranteed
Clients follow all links, including these, at their own discretion. Neither
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can drop ', including these," here. I think.

permissions, nor the capability to make a successful call to that link, is guaranteed
solely by the existence of a relationship.


##### Example

The example below shows how relationships in the BitBucket API can be represented
with the link schema. This example uses `operationId` values to link responses to
by the link schema. This example uses `operationId` values to link responses to
possible operations.

```yaml
Expand Down Expand Up @@ -2280,7 +2280,7 @@ components:
href: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{$response.body#/username}'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this should be operationRef: not href: - @darrelmiller please confirm.

```

Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when
Prefixing `operationRef` using the _escaped forward-slash_ is necessary when
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs clarification because the URL includes both escaped and unescaped forward slashes.

The URL (right hand side) here is a reference to the path /2.0/repositories/ and the / characters in that path are escaped by converting them to the character sequence ~1. (that is a tilde and the numeral one), yielding the JSON path element ~12.0~1repositories~1 . These forward slashes are escaped because this part of the JSON reference refers to an element in the JSON document with the key /2.0/repositories/ -- a child of the paths object in that OpenAPI document.

The / characters in the other part of the href, namely https://na2.gigantic-server.com/#/paths/ should not be escaped because the first part is the ___location of an OpenAPI document and #/paths/ is the path to the children of the paths object.

The final forward slash in {$response.body#/username} is not escaped because that is a second (nested) JSON reference which refers to the top-level username attribute in the runtime response body, such as

{
   "id" : "u284230",
  "username" : "darrelmiller"
}

Forward slashes would be necessary here if and only if items in the response body themselves contain forward slashes, such as accessing the members in the the following JSON response body:

{
  "codeNames" : {
     "mi/0" : "darrelmiller",
     "mi/6" : "u284230",
   }
}

If one wanted to insert the value associated with "mi/6" into the link URL, that forward slash would have to be escaped: {$response.body#/codeNames/mi~16}

Again, @darrelmiller please confirm. Perhaps this level of detail is not necessary, but some explanation of slash escaping should be here.

using JSON references.

#### <a name="headerObject"></a>Header Object
Expand Down