Version our Endpoints and Filters #1119

Activity

1. rachelbaker

   added

   Infrastructure

   Discussion

   on Apr 19, 2015
2. rachelbaker

   added this to the 2.0 Beta 1 milestone on Apr 19, 2015
3. danielbachhuber commented on Apr 19, 2015

   

   danielbachhuber

   on Apr 19, 2015

   Member

   More actions

   we still need to add versioning to the core endpoints

   We should discuss the purpose of versioning too. To me, having versioned routes set the expectation responses will be consistent. Given we're letting plugin authors do whatever, responses can't ever be expected to be consistent. I'm not sure what versioned routes are intended to solve.
4. rachelbaker commented on Apr 20, 2015

   

   rachelbaker

   on Apr 20, 2015

   MemberAuthor

   More actions

   1. We need to add support for versioning to our endpoint registration function so that plugins can version their own endpoints. Example: /gravity-forms/v2.3/forms
   2. Having endpoint versions allows us to make breaking changes with new API versions.
   3. Support for endpoint versions was a requirement for the v2.0 rewrite. Core Merging Plan for the API #571
5. apokalyptik commented on Apr 20, 2015

   

   apokalyptik

   on Apr 20, 2015

   More actions

   To the point of not being able to version because we can't expect responses to be consistent due to plugins changing data around.

   I understand what you mean. But I think we don't need to get too carried away with being too literal. We've had some discussions like this in the past about trying to police what devs to, and it's not a good idea. What we can and should do is police ourselves, and give devs the ability to do the same. Worrying about the possibility of a plugin breaking the site (or in this case versioning of the API) isn't a super good use of our time. Doing the right thing for ourselves and providing others the tools to walk in our footsteps certainly is.
6. rmccue commented on Apr 20, 2015

   

   rmccue

   on Apr 20, 2015

   Member

   More actions

   Agreed with @apokalyptik. The version number is a strong indicator of what to expect (i.e. "which API handling class should I use?"), but clients still need to be robust enough to know the response might change independently of that.

   With regards to versioning internally: it's always been my intent to change the prefixes on everything for v2. This sounds like a good time to do it. V2 can use WP_REST_ for class names, and rest_ for filters. If/When we do a v3, we can pick a different prefix then, possibly just WP_REST_V3 and rest_v3, but I don't think we should be too tied to that.

   Versioning externally: we decided back at WCNYC to add the version to the URLs. Originally, we thought this would be a separate parameter to register_api_route, but we changed our thinking on enforcing this permanently, as it can encourage copy-and-paste antipatterns. Instead, the plan is that you can handle versioning inside the "namespace" parameter, so we basically just need to change our code from register_api_route( 'wp', ... to register_api_route( 'wp/v2', ... and we should be OK.
7. danielbachhuber

   self-assigned this

   on Apr 22, 2015
8. danielbachhuber commented on Apr 28, 2015

   

   danielbachhuber

   on Apr 28, 2015

   Member

   More actions

   Do we want to do a filter pass here too? Seems like there's a fair amount of low-hanging fruit in this regard.
9. rachelbaker

   added

   #Blessed

   on Apr 28, 2015
10. rachelbaker

    closed this as completedon Apr 29, 2015