We’ve finally come to the end of Summer of Code, so it’s time for the final GSoC release in this slightly late update (hey, would it be a post by me if not?). This release is mainly a stability release, so there are only minor changes:

• Huge documentation update – Guides on getting started and extending the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. are now available for your perusal
• Add generic CPT class – Plugins are now encouraged to extend
  WP_JSON_CustomPostType and get free hooking for common actions. This
  removes most of the boilerplate that you needed to write for new CPT-based
  routes and endpoints (#380)
• Use defined filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. priorities for endpoint registration – It’s now easier to
  inject your own endpoints at a defined point
• Update the schema – Now includes documentation on the Media entity, plus more
  (#264)
• Add better taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. support – You can now query for taxonomies and terms directly. The routes here might seem strange (/posts/types/post/taxonomies/category for example), but the intention is to future-proof them as much as possible (#275)
• Ensure the JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org is relative to the home URL (#375)
• Check all date formats for If-Unmodified-Since (#378)
• Register the correct URL for the JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. library (#376)
• Correct the usage of metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. links (#379)
• Add filters for post type and post status data (#380)
• Separate parent post and parent comment relation (#330)

The big feature for this final week is a bunch of documentation changes. I’ve created guides and documents on how to use the API, intended for both beginners and experts. I’d especially like to highlight the Getting Started guide, as well as the Extending the API guide for pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party developers. The documentation in the past has been less than fantastic, so I’ve made a concerted effort towards it this week. In addition, I’ve also fixed up all the remaining bugs reported via TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress..

Now that GSoC’s over, what’s next? The aim with the project is to now move it from a solo project to a team one, and to that end, I’ve been working on assembling a fantastic team to work on the project with, with aim to integrate the API into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. in the future. 3.8 time is fast approaching, so we’ve elected to aim for 3.9 as a more realistic target, although the advantage of the Feature as a Plugin method of development is that we’re not locked down here.

We’re held two meetings so far as a team, and I’ll announce a proper office hours time next week, but I’m also looking to try something new with the organisation of the team. More to come on that in the next team update, but in the meantime, you can check out the internal team discussion site. Anyone looking to get involved in the team is welcome to join as always, but I’d ask that only those serious about working on the project join, as there are a fair few people committed already.

Thanks to everyone, especially my mentors and Jen, for making this project a joy to work on so far. Here’s hoping we can keep the momentum as we push forward with the project.

#gsoc, #gsoc2013, #json-api, #rest-api

This week, I finally have a new release for you! Version 0.5 is now available, with the following changes (and more!):

• Add support for media – This has been a long time coming, and it’s finally at a point where I’m happy to push it out. Good luck. (#272)
• Separate the post-related endpoints – Post-related endpoints are now located in the WP_JSON_Posts class. When implementing custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. support, it’s recommended to subclass this.

  The various types are now also only registered via hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same., rather than directly in the server class, which should make it easier to override them as well (#348)

• Add page support – This is a good base if you’re looking to create your own custom post type support (#271)
• Switch from fields to context – Rather than passing in a list of fields that you want, you can now pass in a context (usually view or edit) (#328).
• Always send headers via the server handler – Endpoints are now completely separate from the request, so the server class can now be used for non-HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands./JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. handlers if needed (#293)
• Use better error codes for disabled features (#338)
• Send X-WP-Total and X-WP-TotalPages headers for information on post/pagination counts (#266)

As always, the full changes are available if you’re interested.

This week finally brings media into the fold. The process for uploading media is a little different to creating normal posts, so here’s how you do it.

First, upload the file via a POST request to /media. This can either be as a standard HTTP multipart body, with the name field set to file, or as a raw file in the body with the Content-Type headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.. (You can also optionally send a Content-MD5 header if you’d like the server to check the consistency of your file.) This will give you a 201 Created status, and point you to the new resource. You can now update that resource with the correct post data.

This multistep procedure is required to enable raw file uploads, and I’m not entirely pleased with it, but it’s the only way without requiring multipart requests. I’d love to have feedback on this system, as I think practical use will eventually reveal the correct method here.

So, it’s time to start winding up the Summer of Code portion of the project. There’s still one week left for the Summer of Code project, so you may still see a release next week, but most likely in the form of smaller updates, especially with documentation and testing. As I finish up, it’s time to look forward to the future of the project. The plan is to form a Feature as a PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party team as we work towards coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. integration in future releases. People have already volunteered for the team back in the 3.8 scoping days, and I’ll be getting in contact with them shortly, but it’s not too late to nominate yourself for the team; let me know if you’re interested.

Thanks to everyone for testing and for your feedback. Stay beautiful.

#gsoc, #gsoc2013, #json-api, #rest-api

It’s been a while since you’ve all heard from me, so I wanted to check in and assure you I am still alive. I’ve been plodding along behind the scenes with the JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. and mostly getting design documents sorted.

The big feature I’m working on at the moment – media – has turned out to be tricker than I initially thought. While media is technically handled via custom post types, it’s a completely different kettle of fish to normal post types, so I’ve been working through the conceptual issues behind this to ensure that the API stays consistent both internally and externally. I really believe that it’s worth my time to sit down and consider these conceptual issues in depth rather than pumping out the feature as soon as possible. (The implementation of the media-related endpoints is working locally, but I don’t want to push this up while it’s still in flux.)

I still hold out hope to push through media, but will likely reduce the scope of the other tasks to compensate, due to the complexity of media and the time it has taken so far. I’d like to personally apologise for this, this is a result of improper scheduling for the second half of the project.

Personally, the past month or so has been pretty stressful as well, due to a number of other things going on in the background. Balancing this project with university work has become a big issue recently, so I’m working through this as best as I can. Ideally, my preferred option at this point would be to push this project out of the Summer of Code phase and into the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. team phase rather than continuing to work on the project in isolation.

Along those lines, revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. will be bumped from the Summer of Code phase completely. While they are part of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. functionality, they’re a rather large task that is secondary in importance to media and also behind taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. handling. I’d love to see these in the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party at some point, but that won’t be happening during the Summer of Code phase. What I would love is for someone to volunteer to develop this (in a separate plugin for now, thanks to GSoC’s restrictions) for integration back in as soon as possible, which would also help with validating the API’s usefulness.

So again, sorry and hopefully I’ll have something better to show you next week. Thanks for your patience.

#gsoc, #gsoc2013, #json-api, #rest-api

After a week’s hiatus thanks to WCSF and the midsemester review, I’m back with a new release of WP APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.! Version 0.4 is now available with the following changes:

• Add Backbone-based models and collections – These are available to your code by declaring a dependency on wp-api (#270)
• Check json_route before using it (#336)
• Conditionally load classes (#337)
• Add additional test helper pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party – Provides code coverage as needed to the API client tests. Currently unused. (#269)
• Move json_url() and get_json_url() to plugin.php – This allows using both outside of the API itself (#343)
• getPost(0) now returns an error rather than the latest post (#344)

As always, the full changes are available if you’re interested.

This release brings the first version of the JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. API, based on Backbone models and collections. To use it, simply declare `wp-api` as a dependency to your script, then start using the `wp.api` classes. Here’s a quick example of how to use it:

var posts = new wp.api.collections.Posts();
posts.fetch({
	success: function (posts) {
		var post = posts.at(0);
		var title = post.get('title');
		post.set('title', title + ' (Updated!)');
		post.save();
	}
});

These are intended purely as building blocks for your own software. I had been looking at rewriting P2P2 A free theme for WordPress, known for front-end posting, used by WordPress for development updates and project management. See our main development blog and other workgroup blogs. partially to use these, however it appears that would require gutting P2 and basically starting from scratch, due to P2’s architecture. I’d love to see what you can do with this though, and bonus points if you can get a API-ified P2!

The coming week will introduce some specialised page handling as an example of how to enable custom post typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept. support, plus the beginning of the media/attachment-related APIs. These will probably be a fair bit of work, so it’s possible only basic functionality will land next week.

#gsoc, #gsoc2013, #json-api, #rest-api

This week is a little different to the previous ones, as it’s a primarily testing focussed week. I’m skipping the release for this week in favour of just an update post.

I noticed fairly late this week that the aforementioned client library wasn’t actually public and available to you guys, so I’ve now fixed that up. Given the lack of comments, I’d hazard a guess this also means no one tried using it. 🙂

Previous Week

Over the past week, I’ve been looking at a variety of testing-related items, including code coverage and schema validation. I’ve finally sorted the schema validation out with the help of a JSON Schema validation library, after much messing around. The unit tests now integrate this schema validation with the normal testing suite, which should ensure that the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is conformant to the specification as well as fully functional. I do suspect that the schema is slightly outdated and is missing a few items, so I’ll be ensuring the documentation and schema are consistent in the next week.

Another area of the testing that I’ve been looking at is working with code coverage. After exploring the inner workings of PHPUnit’s code coverage, I think I’ve worked out a solution using a test helper plugin. This gathers the statistics on the server, then serialises them to send them back to the client. This still needs the PHPUnit end to connect to, which should be simple once I work out how to override the PHP_CodeCoverage object. (Help here would be appreciated if anyone has familiarity with PHPUnit.)

I’ve also started work on the Backbone client, however that’s currently not in a state to release. The plan here is to create a generic set of Backbone-based classes that can be used as a library, with the proof-of-concept itself being a theme based on P2P2 A free theme for WordPress, known for front-end posting, used by WordPress for development updates and project management. See our main development blog and other workgroup blogs.. I’ve started work on the Backbone side of things, however I’ve not worked on much here with the theme side. I suspect that P2’s JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. will be discarded in large part, but hopefully I can avoid that as much as possible.

Next week, you can look forward to more testing updates and the Backbone client. I’ll also be pushing out a new version with some bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes (thanks to Mike Schinkel for reporting these) as well as the usual slate of updates.

Documentation

I’ve also discovered that my documentation thus far has been a little lacking, so here’s a bit of an intro to using the API.

After downloading and activating the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, your site will now capable of serving up data from its API. The API is accessible at /wp-json.php from your site (if you’re not sure where this is, copy your adminadmin (and super admin) URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org and replace wp-admin with wp-json.php), with the specific route added after this. For example, the index is available at /wp-json.php/ and a list of your posts is available at /wp-json.php/posts.

If you’d just like to take a look around, you can view this in your browser and navigate via the links in the JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML.. I personally use JSON View for this in Firefox, which converts the URLs in the data into proper hyperlinks as well as making it easier to view the data. The API uses a concept called HATEOAS, which basically means that all the possible data is discoverable via these links.

Some endpoints will add extra data if you’re logged in with the correct permissions. You can log in via the normal WP login page if you’re just viewing this in your browser (using cookie-based authentication), but if you’re accessing the API programatically, the API also has built-in support for HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. Basic authentication. (OAuth support is not planned for the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of the plugin, but my OAuth provider plugin might be a good start for anyone who wants to write this as a plugin.)

I’m always open to questions regarding how to use this, so let me know here or on Twitter if there’s anything I can do to help you out.

#gsoc, #gsoc2013, #json-api, #rest-api

Time for another release of the JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.! We’re closing in on midsemester evaluation, so it’s time to get our test on and ensure that everything’s working well. Only small updates to the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. itself this week, but also the first introduction of the comment API:

• Add initial comment endpoints to get comments for a post, and get a single comment (#320)
• Return a Post entity when updating a post, rather than wrapping it with useless text (#329)
• Allow filtering the output as well as input. You can now use the json_dispatch_args filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. for input as well as the json_serve_request filter for output to serve up alternative formats (e.g. MsgPack, XML (if you’re insane))
• Include a profile link in the index, to indicate the JSON Schema that the API conforms to. In the future, this will be versioned.

The big part of this week is the introduction of the testing suite and reference client. These are now both available on GitHub and I’d love for you to run them and test out the API. There’s currently one known bug that causes one of the tests to fail, which I’ll be handling in 0.4 due to the large scope of the issue.

I’m planning to continue work on the test suite this week, due to the large scope of the testing suite. Ideally, I’d like to get up around the 90% mark for code coverage (which I’ve done previously on my Requests library), however I’m not sure as to how coverage can be measured in this case, so I’ll also be investigating this. The coming week will also involve creating a Backbone-based sample theme as a proof-of-concept of real world use. In addition, coming up I’ll be consulting with Max Cutler from the mobile team and ensuring that any possible issues are sorted out at this early stage.

As always, I appreciate all and any feedback on the project. This week and the next will be boring for you guys in terms of new features as we approach midsemester review, so I’d love you to get out there and break the API. If you can find problems with it, please file them and let me know so I can work them into the testing suite.

#gsoc, #gsoc2013, #json-api, #rest-api

It’s that time of week again folks (and actually on-time this time)! Version 0.2 of the JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. includes my changes from the past week, including:

• Allow all public query vars to be passed to WP Query – Some private query vars
  can also be passed in, and all can if the user has edit_posts
  permissions (#311)
• Pagination can now be handled by using the page argument without messing
  with WP Query syntax (#266)
• The index now generates links for non-variable routes (#268)
• Editing a post now supports the If-Unmodified-Since headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes.. Pass this in to
  avoid conflicting edits (#294)
• Post types and post statuses now have endpoints to access their data (#268)

You can also view all changes if that’s your style.

As you can see, it’s a bit of a quiet week in terms of new features, but with the exception of revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision., attachments, and comments, the post APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. is now considered feature complete. Implementers can now expect that there won’t be any major changes to the post API.

Since you’ve all been so great, I’ve thrown in a bonus for this week. I’ve created a small proof-of-concept of extending the API for a multisitemultisite Used to describe a WordPress installation with a network of multiple blogs, grouped by sites. This installation type has shared users tables, and creates separate database tables for each blog (wp_posts becomes wp_0_posts). See also network, blog, site installation, which is now available via GitHub. Keep in mind that this is just a proof-of-concept, so it doesn’t have too much implemented. (This is also not covered under the scope of the GSOC project, so pull requests are most welcome!)

In the next couple of weeks, development will be focused around creating tests and example implementations. While this is occurring, I plan to also implement commenting, which was not in the original scope, but is still fairly important.

As always, feedback is welcome!

#gsoc, #gsoc2013, #json-api, #rest-api

It’s time for the first weekly release of the APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party for everyone to sink their teeth into. This post comes to you a few days late, as I’ve unfortunately been a bit sick during the week.

You can either install it from GitHub or from WordPress.org.

Here’s what’s changed since the pre-GSoC version:

• Enable the code to be used via the plugin architecture (now uses rewrite rules if running in this mode)
• Design documents are now functionally complete for the current codebase (#264)
• Add basic writing support (#265)
• FilterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. fields by default – Unfiltered results are available via their corresponding *_raw key, which is only available to users with edit_posts (#290)
• Use correct timezones for manual offsets (GMT+10, e.g.) (#279)
• Allow permanently deleting posts (#292)

You can also check out the full changelog if you’re interested.

Astute observers amongst you will notice that the main collection parts (#266, #267) are missing from this release; I’m slightly behind on the release process due to just finishing up final exams and illness. Don’t worry though, I preplanned for this by allowing myself a buffer week before the midsemester deadline.

Feedback is very welcome!

#gsoc, #gsoc2013, #json-api, #rest-api