Skip to content

Commit 2a0d7dd

Browse files
kadamwhitekadamwhite
committed
Reorder global parameters page (put _embed earlier)
This page is currently unordered, so this PR restructures it to put the most-used/useful properties first. My sense of what is useful is informed primarily by how frequently I have heard each one referenced since the merge of the API.
1 parent 6a51f43 commit 2a0d7dd

File tree

1 file changed

+26
-30
lines changed

1 file changed

+26
-30
lines changed

‎using-the-rest-api/global-parameters.md‎

Lines changed: 26 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -36,34 +36,18 @@ You can also request specific deeply-nested properties within a complex meta obj
3636
?_fields=meta.key_name.nested_prop.deeply_nested_prop,meta.key_name.other_nested_prop
3737
```
3838

39-
## `_jsonp`
40-
41-
The API natively supports [JSONP](https://en.wikipedia.org/wiki/JSONP) responses to allow cross-domain requests for legacy browsers and clients. This parameter takes a JavaScript callback function which will be prepended to the data. This URL can then be loaded via a `<script>` tag.
4239

43-
The callback function can contain any alphanumeric, `_` (underscore), or `.` (period) character. Callbacks which contain invalid characters will receive a HTTP 400 error response, and the callback will not be called.
40+
## `_embed`
4441

45-
[info]
46-
Modern browsers can use <a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross-Origin Resource Sharing (CORS)</a> preflight requests for cross-domain requests, but JSONP can be used to ensure support with all browsers.
42+
Most resources include links to related resources. For example, a post can link to the parent post, or to comments on the post. To reduce the number of HTTP requests required, clients may wish to fetch a resource as well as the linked resources. The `_embed` parameter indicates to the server that the response should include these embedded resources.
4743

48-
<ul>
49-
<li><a href="http://caniuse.com/#feat=cors">Browser Support</a></li>
50-
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS">MDN Article on CORS</a></li>
51-
</ul>
52-
[/info]
44+
Embed mode is enabled if the `_embed` parameter is passed in the query string (GET parameter). This parameter does not require a value (i.e. `?_embed` is valid), however can be passed "1" as a value if required by a client library.
5345

54-
For example:
46+
[info]For future compatibility, other values should not be passed.[/info]
5547

56-
```html
57-
<script>
58-
function receiveData( data ) {
59-
// Do something with the data here.
60-
// For demonstration purposes, we'll simply log it.
61-
console.log( data );
62-
}
63-
</script>
64-
<script src="https://example.com/wp-json/?_jsonp=receiveData"></script>
65-
```
48+
Resources in embed mode will contain an additional `_embedded` key next to the `_links` key containing the linked resources. Only links with the `embeddable` parameter set to `true` will be embedded.
6649

50+
For more about linking and embedding, see the [Linking and Embedding](https://developer.wordpress.org/rest-api/linking-and-embedding/) page.
6751

6852
## `_method` (or `X-HTTP-Method-Override` header)
6953

@@ -85,7 +69,6 @@ Host: example.com
8569
X-HTTP-Method-Override: DELETE
8670
```
8771

88-
8972
## `_envelope`
9073

9174
Similarly to `_method`, some servers, clients, and proxies do not support accessing the full response data. The API supports passing an `_envelope` parameter, which sends all response data in the body, including headers and status code.
@@ -126,17 +109,30 @@ HTTP/1.1 200 OK
126109
}
127110
```
128111

112+
## `_jsonp`
129113

130-
## `_embed`
131-
132-
Most resources include links to related resources. For example, a post can link to the parent post, or to comments on the post. To reduce the number of HTTP requests required, clients may wish to fetch a resource as well as the linked resources. The `_embed` parameter indicates to the server that the response should include these embedded resources.
114+
The API natively supports [JSONP](https://en.wikipedia.org/wiki/JSONP) responses to allow cross-domain requests for legacy browsers and clients. This parameter takes a JavaScript callback function which will be prepended to the data. This URL can then be loaded via a `<script>` tag.
133115

134-
Embed mode is enabled if the `_embed` parameter is passed in the query string (GET parameter). This parameter does not require a value (i.e. `?_embed` is valid), however can be passed "1" as a value if required by a client library.
116+
The callback function can contain any alphanumeric, `_` (underscore), or `.` (period) character. Callbacks which contain invalid characters will receive a HTTP 400 error response, and the callback will not be called.
135117

136118
[info]
137-
For future compatibility, other values should not be passed.
119+
Modern browsers can use <a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross-Origin Resource Sharing (CORS)</a> preflight requests for cross-domain requests, but JSONP can be used to ensure support with all browsers.
120+
121+
<ul>
122+
<li><a href="http://caniuse.com/#feat=cors">Browser Support</a></li>
123+
<li><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS">MDN Article on CORS</a></li>
124+
</ul>
138125
[/info]
139126

140-
Resources in embed mode will contain an additional `_embedded` key next to the `_links` key containing the linked resources. Only links with the `embeddable` parameter set to `true` will be embedded.
127+
For example:
141128

142-
For more about linking and embedding, see the [Linking and Embedding](https://developer.wordpress.org/rest-api/linking-and-embedding/) page.
129+
```html
130+
<script>
131+
function receiveData( data ) {
132+
// Do something with the data here.
133+
// For demonstration purposes, we'll simply log it.
134+
console.log( data );
135+
}
136+
</script>
137+
<script src="https://example.com/wp-json/?_jsonp=receiveData"></script>
138+
```

0 commit comments

Comments
 (0)