Skip to content

Commit 766e96e

Browse files
rmccuermccue
committed
Merge branch 'gh-pages' into reworking
Conflicts: .gitignore _includes/header.html index.md
2 parents 14226a3 + 36e79a2 commit 766e96e

18 files changed

+309
-58
lines changed

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,6 @@
1+
.DS_Store
2+
composer.lock
3+
Gemfile.lock
4+
vendor
15
_site/
26
.sass-cache/

‎Phakefile.php

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<?php
2+
require_once dirname( __FILE__ ) . '/vendor/autoload.php';
3+
4+
if ( ! getenv( 'WP_API_DEV_DOMAIN' ) ) {
5+
echo "`WP_API_DEV_DOMAIN` environment variable must be set to build the site.";
6+
exit(1);
7+
}
8+
9+
function render( $path, $binding ) {
10+
$m = new Mustache_Engine;
11+
$template = file_get_contents( __DIR__ . "/templates/$path" );
12+
return $m->render( $template, $binding );
13+
}
14+
15+
desc( 'Build the endpoint documentation.' );
16+
task( 'endpoint-list', function( $app ){
17+
18+
$endpoints = array(
19+
'comments' => array(
20+
'plural_name' => 'Comments',
21+
'singular_name' => 'Comment',
22+
'schema_route' => '/wp-json/wp/v2/comments/schema',
23+
),
24+
'media' => array(
25+
'plural_name' => 'Media',
26+
'singular_name' => 'Attachment',
27+
'schema_route' => '/wp-json/wp/v2/media/schema',
28+
),
29+
'pages' => array(
30+
'plural_name' => 'Pages',
31+
'singular_name' => 'Page',
32+
'schema_route' => '/wp-json/wp/v2/pages/schema',
33+
),
34+
'posts' => array(
35+
'plural_name' => 'Posts',
36+
'singular_name' => 'Post',
37+
'schema_route' => '/wp-json/wp/v2/posts/schema',
38+
),
39+
'post_meta' => array(
40+
'plural_name' => 'Meta for a Post',
41+
'singular_name' => 'Meta for a Post',
42+
'schema_route' => '/wp-json/wp/v2/posts/meta/schema',
43+
),
44+
'post_revisions' => array(
45+
'plural_name' => 'Revisions for a Post',
46+
'singular_name' => 'Revision for a Post',
47+
'schema_route' => '/wp-json/wp/v2/posts/revisions/schema',
48+
),
49+
'taxonomies' => array(
50+
'plural_name' => 'Taxonomies',
51+
'singular_name' => 'Taxonomy',
52+
'schema_route' => '/wp-json/wp/v2/taxonomies/schema',
53+
),
54+
'terms' => array(
55+
'plural_name' => 'Terms',
56+
'singular_name' => 'Term',
57+
'schema_route' => '/wp-json/wp/v2/terms/category/schema',
58+
),
59+
'users' => array(
60+
'plural_name' => 'Users',
61+
'singular_name' => 'User',
62+
'schema_route' => '/wp-json/wp/v2/users/schema',
63+
),
64+
);
65+
66+
$dev_domain = rtrim( getenv( 'WP_API_DEV_DOMAIN' ), '/' );
67+
68+
foreach( $endpoints as $file_name => $attributes ) {
69+
70+
$response = Requests::get( $dev_domain . $attributes['schema_route'] );
71+
if ( 200 !== $response->status_code ) {
72+
echo "Error fetching schema: {$attributes['schema_route']} (HTTP code {$response->status_code})";
73+
exit(1);
74+
}
75+
76+
$response_data = json_decode( $response->body );
77+
// Prepare the data because Mustache is opinionated
78+
$properties = array();
79+
if ( ! empty( $response_data->properties ) ) {
80+
foreach( $response_data->properties as $name => $args ) {
81+
$property = array(
82+
'name' => $name,
83+
'description' => ! empty( $args->description ) ? $args->description : '',
84+
'type' => ! empty( $args->type ) ? $args->type : '',
85+
'context' => ! empty( $args->context ) ? implode( $args->context, ', ' ) : '',
86+
);
87+
if ( ! empty( $args->format ) ) {
88+
$property['type'] .= ',' . $args->format;
89+
}
90+
$properties[] = $property;
91+
}
92+
}
93+
94+
$attributes['schema_properties'] = $properties;
95+
file_put_contents( dirname( __FILE__ ) . '/_includes/routes/' . $file_name . '.md', render( 'endpoint.mustache', $attributes ) );
96+
}
97+
98+
});
99+
100+
desc( 'Build the site.' );
101+
task( 'default', 'endpoint-list' );

‎README.md

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
These files comprise v2.wp-api.org. The endpoint documentation is programmatically, but manually, generated from the API.
2+
3+
### Setup
4+
5+
1. Install [Composer](http://getcomposer.org/).
6+
7+
2. Install dev dependencies with `composer install --dev`
8+
9+
3. Set the domain for WP-API: `export WP_API_DEV_DOMAIN=http://wordpress-develop.dev` (or similar)
10+
11+
4. Build the endpoint documentation:
12+
13+
```bash
14+
vendor/bin/phake
15+
```

‎_includes/extending/internal-classes.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Internal Classes
2+
3+
WP-API has a deliberate design pattern for its internal classes. They can be categorized as either _infrastructure_ or _endpoints_.
4+
5+
Infrastructure classes support the endpoint classes. They handle the logic for WP-API without performing any data transformation. Endpoint classes, on the other hand, encapsulate the functional logic necessary to perform CRUD operations on WordPress resources. More specifically, our infrastructure classes include `WP_REST_Server` and `WP_REST_Request`, where our endpoint classes include `WP_REST_Posts_Controller` and `WP_REST_Users_Controller`.
6+
7+
Let's dive into what each infrastructure class does:
8+
9+
* `WP_REST_Server`: The main controller for WP-API. Routes are registered to the server within WordPress. When `WP_REST_Server` is called upon to serve a request, it determines which route is to be called, and passes the route callback a `WP_REST_Request` object. `WP_REST_Server` also handles authentication, and can perform request validation and permissions checks.
10+
* `WP_REST_Request`: An object to represent the nature of the request. This object includes request details like request headers, parameters, and method, as well as the route. It can also perform request validation and sanitization.
11+
* `WP_REST_Response`: An object to represent the nature of the response. This class extends `WP_HTTP_Response`, which includes headers, body, and status, and provides helper methods like `add_link()` for adding linked media, and `query_navigation_headers()` for getting query navigtion headers.
12+
13+
All endpoint classes extend `WP_REST_Controller`. This class is designed to represent a consistent pattern for manipulating WordPress resources. `WP_REST_Controller` implements these methods:
14+
15+
* `register_routes()`: After instantiating the class for the first time, call `register_routes()` to register the resource's routes to the server.
16+
* `get_items()`: Get a collection of existing entities.
17+
* `get_item()`: Get an existing entity. If the entity doesn't exist, HTTP error code 404 should be returned. If the requester doesn't have permission to access the entity, a HTTP error code 403 should be returned.
18+
* `create_item()`: Create a new entity, given a valid `WP_REST_Request`. If creation is successful, a `WP_REST_Response` should be returned with HTTP `status=201` and `location` header to the new resource. If creation is errored in some form, the appropriate HTTP error code and message should be returned.
19+
* `update_item()`: Update an existing entity, given a valid `WP_REST_Request`.
20+
* `delete_item()`: Delete an existing entity, given a valid `WP_REST_Request`. If deletion is errored in some way, the appropriate HTTP error code should be returned.
21+
* `get_items_permissions_check()`: Before calling the callback, check whether a given request has permissions to a collection of a resource.
22+
* `get_item_permissions_check()`: Before calling the callback, check whether a given request has permissions to get an individual resource.
23+
* `create_item_permissions_check()`: Before calling the callback, check whether a given request has permissions to create an individual resource.
24+
* `update_item_permissions_check()`: Before calling the callback, check whether a given request has permissions to update an individual resource.
25+
* `delete_items_permissions_check()`: Before calling the callback, check whether a given request has permissions to delete an individual resource.
26+
* `prepare_item_for_response()`: TK
27+
* `prepare_response_for_collection()`: TK
28+
* `filter_response_by_context()`: TK
29+
* `get_item_schema()`: Get the resource's schema, conforming to JSON Schema.
30+
31+
When interacting with an endpoint that implements `WP_REST_Controller`, a HTTP client can expect each endpoint to behave in a similar way.

‎_includes/reference/glossary.md

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
## Glossary
2+
3+
New to REST APIs? Get up to speed with phrases used throughout our documentation.
4+
5+
### Controller
6+
7+
[Model-View-Controller](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) is a standard pattern in software development. If you aren't already familiar it, you should do a bit of reading to get up to speed.
8+
9+
Within WP-API, we've adopted the controller concept to have a standard pattern for the classes representing our resource endpoints. All resource endpoints extend `WP_REST_Controller` to ensure they implement common methods.
10+
11+
### HEAD, GET, POST, PUT, and DELETE Requests
12+
13+
These "HTTP verbs" represent the _type_ of action a HTTP client might perform against a resource. For instance, `GET` requests are used to fetch a Post's data, whereas `DELETE` requests are used to delete a Post. They're collectively called "HTTP verbs" because they're standardized across the web.
14+
15+
If you're familiar with WordPress functions, a `GET` request is the equivalent of `wp_remote_get()`, and a `POST` request is the same as `wp_remote_post()`.
16+
17+
### HTTP Client
18+
19+
The phrase "HTTP Client" refers to the tool you use to interact with WP-API. You might use [Postman](https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en) to test requests in your browser, or [httpie](https://github.com/jakubroztocil/httpie) to test requests at the commandline. WordPress itself represents a HTTP Client in that you can use the `WP_HTTP` class of functions (e.g. `wp_remote_get()`) to make HTTP requests.
20+
21+
### Resource
22+
23+
A "Resource" is a _discrete entity_ within WordPress. You may know these resources already as Posts, Pages, Comments, Users, Terms, Plugins, and so on. WP-API permits HTTP clients to perform CRUD operations against resources (CRUD stands for Create, Read, Update, and Delete).
24+
25+
Pragmatically, here's how you'd typically interact with WP-API resources:
26+
27+
* `GET /wp-json/wp/v2/posts` to get a collection of Posts. This is roughly equivalent to using `WP_Query`.
28+
* `GET /wp-json/wp/v2/posts/123` to get a single Post with ID 123. This is roughly equivalent to using `get_post()`.
29+
* `POST /wp-json/wp/v2/posts` to create a new Post. This is roughly equivalent to using `wp_insert_post()`.
30+
* `DELETE /wp-json/wp/v2/posts/123` to delete Post with ID 123. This is roughly equivalent to `wp_delete_post()`.
31+
32+
### Routes / Endpoints
33+
34+
"Routes" and "Endpoints" are synonymous. These words essentially mean everything after the domain in a URL. For instance, with the URL `http://wordpress-develop.dev/wp-json/wp/v2/posts/123`, the route is `wp/v2/posts/123`. The route doesn't include `wp-json` because `wp-json` is the base path for our API. All other URLs are handled by WordPress' default request handling.
35+
36+
### Schema
37+
38+
A "schema" is a representation of the format for WP-API's response data. For instance, the Post schema communicates that a request to get a Post will return `id`, `title`, `content`, `author`, and other fields. Our schemas also indicate the type each field is, provide a human-readable description, and show which contexts the field will be returned in.

‎_includes/routes/comments.md

+5-6
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,21 @@
66
| :------- | :--- | :---------- | :------ |
77
| `id` | integer | Unique identifier for the object. | view, edit |
88
| `author` | integer | The ID of the user object, if author was a user. | view, edit |
9-
| `author_email` | email | Email address for the object author. | edit |
9+
| `author_email` | string,email | Email address for the object author. | edit |
1010
| `author_ip` | string | IP address for the object author. | edit |
1111
| `author_name` | string | Display name for the object author. | view, edit |
12-
| `author_url` | uri | Url for the object author. | view, edit |
12+
| `author_url` | string,uri | Url for the object author. | view, edit |
1313
| `author_user_agent` | string | User agent for the object author. | edit |
1414
| `content` | object | The content for the object. | view, edit |
15-
| `date` | date-time | The date the object was published. | view, edit |
16-
| `date_gmt` | date-time | The date the object was published as GMT. | edit |
15+
| `date` | string,date-time | The date the object was published. | view, edit |
16+
| `date_gmt` | string,date-time | The date the object was published as GMT. | edit |
1717
| `karma` | integer | Karma for the object. | edit |
18-
| `link` | uri | URL to the object. | view, edit |
18+
| `link` | string,uri | URL to the object. | view, edit |
1919
| `parent` | integer | The ID for the parent of the object. | view, edit |
2020
| `post` | integer | The ID of the associated post object. | view, edit |
2121
| `status` | string | State of the object. | view, edit |
2222
| `type` | string | Type of Comment for the object. | view, edit |
2323

24-
2524
### List all Comments
2625

2726
### Create a Comment

‎_includes/routes/media.md

+11-11
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@
44

55
| Property | Type | Description | Context |
66
| :------- | :--- | :---------- | :------ |
7-
| `date` | date-time | The date the object was published. | view, edit |
8-
| `date_gmt` | date-time | The date the object was published, as GMT. | edit |
7+
| `date` | string,date-time | The date the object was published. | view, edit |
8+
| `date_gmt` | string,date-time | The date the object was published, as GMT. | edit |
99
| `guid` | object | The globally unique identifier for the object. | view, edit |
1010
| `id` | integer | Unique identifier for the object. | view, edit |
11-
| `link` | uri | URL to the object. | view, edit |
12-
| `modified` | date-time | The date the object was last modified. | view, edit |
13-
| `modified_gmt` | date-time | The date the object was last modified, as GMT. | view, edit |
11+
| `link` | string,uri | URL to the object. | view, edit |
12+
| `modified` | string,date-time | The date the object was last modified. | view, edit |
13+
| `modified_gmt` | string,date-time | The date the object was last modified, as GMT. | view, edit |
1414
| `password` | string | A password to protect access to the post. | edit |
1515
| `slug` | string | An alphanumeric identifier for the object unique to its type. | view, edit |
1616
| `status` | string | A named status for the object. | edit |
@@ -25,14 +25,14 @@
2525
| `media_type` | string | Type of attachment. | view, edit |
2626
| `media_details` | object | Details about the attachment file, specific to its type. | view, edit |
2727
| `post` | integer | The ID for the associated post of the attachment. | view, edit |
28-
| `source_url` | uri | URL to the original attachment file. | view, edit |
28+
| `source_url` | string,uri | URL to the original attachment file. | view, edit |
2929

30-
### List all Attachments
30+
### List all Media
3131

32-
### Create an Attachment
32+
### Create a Attachment
3333

34-
### Retrieve an Attachment
34+
### Retrieve a Attachment
3535

36-
### Update an Attachment
36+
### Update a Attachment
3737

38-
### Delete an Attachment
38+
### Delete a Attachment

‎_includes/routes/pages.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,13 @@
44

55
| Property | Type | Description | Context |
66
| :------- | :--- | :---------- | :------ |
7-
| `date` | date-time | The date the object was published. | view, edit |
8-
| `date_gmt` | date-time | The date the object was published, as GMT. | edit |
7+
| `date` | string,date-time | The date the object was published. | view, edit |
8+
| `date_gmt` | string,date-time | The date the object was published, as GMT. | edit |
99
| `guid` | object | The globally unique identifier for the object. | view, edit |
1010
| `id` | integer | Unique identifier for the object. | view, edit |
11-
| `link` | uri | URL to the object. | view, edit |
12-
| `modified` | date-time | The date the object was last modified. | view, edit |
13-
| `modified_gmt` | date-time | The date the object was last modified, as GMT. | view, edit |
11+
| `link` | string,uri | URL to the object. | view, edit |
12+
| `modified` | string,date-time | The date the object was last modified. | view, edit |
13+
| `modified_gmt` | string,date-time | The date the object was last modified, as GMT. | view, edit |
1414
| `password` | string | A password to protect access to the post. | edit |
1515
| `slug` | string | An alphanumeric identifier for the object unique to its type. | view, edit |
1616
| `status` | string | A named status for the object. | edit |
@@ -34,4 +34,4 @@
3434

3535
### Update a Page
3636

37-
### Delete a Page
37+
### Delete a Page

‎_includes/routes/post_meta.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Post Meta
1+
## Meta for a Post
22

33
### Schema
44

@@ -10,10 +10,10 @@
1010

1111
### List all Meta for a Post
1212

13-
### Create Meta for a Post
13+
### Create a Meta for a Post
1414

15-
### Retrieve Meta for a Post
15+
### Retrieve a Meta for a Post
1616

17-
### Update Meta for a Post
17+
### Update a Meta for a Post
1818

19-
### Delete Meta for a Post
19+
### Delete a Meta for a Post

‎_includes/routes/post_revisions.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
1-
## Post Revisions
1+
## Revisions for a Post
22

33
### Schema
44

55
| Property | Type | Description | Context |
66
| :------- | :--- | :---------- | :------ |
77
| `author` | integer | The ID for the author of the object. | view |
8-
| `date` | date-time | The date the object was published. | view |
9-
| `date_gmt` | date-time | The date the object was published, as GMT. | view |
8+
| `date` | string,date-time | The date the object was published. | view |
9+
| `date_gmt` | string,date-time | The date the object was published, as GMT. | view |
1010
| `guid` | string | GUID for the object, as it exists in the database. | view |
1111
| `id` | integer | Unique identifier for the object. | view |
12-
| `modified` | date-time | The date the object was last modified. | view |
13-
| `modified_gmt` | date-time | The date the object was last modified, as GMT. | view |
12+
| `modified` | string,date-time | The date the object was last modified. | view |
13+
| `modified_gmt` | string,date-time | The date the object was last modified, as GMT. | view |
1414
| `parent` | integer | The ID for the parent of the object. | view |
1515
| `slug` | string | An alphanumeric identifier for the object unique to its type. | view |
1616
| `title` | string | Title for the object, as it exists in the database. | view |
@@ -25,4 +25,4 @@
2525

2626
### Update a Revision for a Post
2727

28-
### Delete a Revision for a Post
28+
### Delete a Revision for a Post

‎_includes/routes/posts.md

+7-7
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,15 @@
44

55
| Property | Type | Description | Context |
66
| :------- | :--- | :---------- | :------ |
7-
| `date` | date-time | The date the object was published. | view, edit |
8-
| `date_gmt` | date-time | The date the object was published, as GMT. | edit |
7+
| `date` | string,date-time | The date the object was published. | view, edit |
8+
| `date_gmt` | string,date-time | The date the object was published, as GMT. | edit |
99
| `guid` | object | The globally unique identifier for the object. | view, edit |
1010
| `id` | integer | Unique identifier for the object. | view, edit |
11-
| link | uri | URL to the object. | view, edit |
12-
| `modified` | date-time | The date the object was last modified. | view, edit |
13-
| `modified_gmt` | date-time | The date the object was last modified, as GMT. | view, edit |
11+
| `link` | string,uri | URL to the object. | view, edit |
12+
| `modified` | string,date-time | The date the object was last modified. | view, edit |
13+
| `modified_gmt` | string,date-time | The date the object was last modified, as GMT. | view, edit |
1414
| `password` | string | A password to protect access to the post. | edit |
15-
| slug | string | An alphanumeric identifier for the object unique to its type. | view, edit |
15+
| `slug` | string | An alphanumeric identifier for the object unique to its type. | view, edit |
1616
| `status` | string | A named status for the object. | edit |
1717
| `type` | string | Type of Post for the object. | view, edit |
1818
| `title` | object | The title for the object. | view, edit |
@@ -33,4 +33,4 @@
3333

3434
### Update a Post
3535

36-
### Delete a Post
36+
### Delete a Post

‎_includes/routes/taxonomies.md

+8-2
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
| Property | Type | Description | Context |
66
| :------- | :--- | :---------- | :------ |
7-
`description` | string | A human-readable description of the object. | view |
7+
| `description` | string | A human-readable description of the object. | view |
88
| `hierarchical` | boolean | Whether or not the type should have children. | view |
99
| `labels` | object | Human-readable labels for the type for various contexts. | view |
1010
| `name` | string | The title for the object. | view |
@@ -14,4 +14,10 @@
1414

1515
### List all Taxonomies
1616

17-
### Retrieve a Taxonomy
17+
### Create a Taxonomy
18+
19+
### Retrieve a Taxonomy
20+
21+
### Update a Taxonomy
22+
23+
### Delete a Taxonomy

0 commit comments

Comments
 (0)