-
Notifications
You must be signed in to change notification settings - Fork 10.8k
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.
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
REST API - Initial Implementation #4055
Conversation
The WC_Comments class is an orphaned global so there's no way for other code to access it in order to remove the `comment_clauses` filter. This changes the add_filter and associated method to static so other code can properly remove the filter for querying order notes
Sorry, I owed you an email about this earlier! I won't have time to look at this until next Wednesday at the earliest, but quick comments:
You should be able to subclass and override this fairly easily, although come to think of it, some JSON stuff is mixed in with the rest, so that should be separated in WP-API.
We also need to handle this in WP-API, so anything here will help us out too. You should be able to implement OAuth completely via a custom authentication handler rather than in the server itself too (although I've haven't checked how you've done this).
The idea with WP-API is that WC-specific data could either be added to the top-level (if it's at Using
Those should definitely be WC-prefixed unless you wholesale bundle WP-API (which is probably a Good Idea). If it makes it easier, we might be able to factor some of the classes out into separate repos. Also happy to look at refactoring code if it makes it easier for you to use now, but I don't want to move around too much just for the plugin-stage of WP-API, since we're aiming for core integration in 3.9.
I'd mix the
If those are in WP-API, patches would be welcome there. :)
If you've got a query, there's a helper method for that. If not, I'd base it off that method.
I'd go with yes. Storing/transmitting prices as floating point numbers is a Bad Idea.
I'd return the variation product, with the parent embedded (ala post parents).
I'll take a more indepth look next week. :)
|
Oh also:
I'd really encourage waiting. If you can't wait until core integration, I'd at least wait until we hit 1.0, as I'm planning to begin ensuring compatibility from that point onwards. In that case, you can bundle the class and conditionally load it if you can't find it in core. |
Real awesome work so far, @maxrice! I'll get to this in more detail later today. Just a couple quick answers on the most critical parts of this discussion, so this can continue.
Fine to add it to the documentation site for now. Think that's a good habitat for it. :)
I can understand what you are saying, but at the same time we really want this API in v2.1 of WooCommerce. Having full forward compatibility for when the API hits WordPress core is obviously a very nice to have, but since this is not going to happen for WordPress 3.8 (correct me if I'm wrong) that's going to take a bit too long. I think it should be pretty well possible to keep it compatible on the end users side completely, while we change the underlying structure some more as soon as the API plugin matures? Until that is stable enough, or possibly going into core, I say we rely on our own code base only and not check for the API being present yet. @maxrice We can continue this way, if it's up to me. We can use the API plugins code already, but lets not add any checks for that plugin (or the API in core) being active for now, so this will continue to work no matter what. I really want this to integrate nicely with the API plugin as soon as it hits WordPress core, but we need to go forward as well and we've postponed the API for too long already. Plus, I think it's a nice way to test the actual code already and contribute back to the API plugin. :) Makes sense? I hope so, but just let me know if not. |
Yep, that's correct. The (unofficial) plan is to hit 1.0 on the plugin and freeze the internals at that point so that things like this can go ahead and be 100% compatible with whatever ends up in core.
From 1.0 onwards, only the higher layers (posts/etc) should change, so it should be possible to rely on the API not changing majorly from then onwards. I have a few things that I'd like to get handled before then, but not that much. (And I'm yet to raise these with the team, but I plan to as soon as I'm back up to full capacity.) Don't get me wrong, I want a WC API yesterday, but making sure it's forwards compatible is nice. :) |
I've discussed the forward compatibility today with @maxrice and we've agreed on the following: We're continuing the development of the REST API as we're doing now, where we're basing it on the WP-API project, but are not using that directly. This way we can help contributing to the original project as our project matures as well, while we don't have to wait for 1.0 of the WP-API before we can do anything. Time is really becoming our biggest issue with version 2.1 and we feel there is a good way around potential issues. As soon as WP-API hits WordPress core, we are going to introduce the v2 of our API, this time completely based on the core implementation of the API. We'll bump the minimum required version of WordPress for the version of WooCommerce implementing the core API, while v1 of our API is going to stay in that WooCommerce release. That way we make the use of the new API opt in and we can make sure that nothing breaks. We can then deprecate v1 of our API quickly after that and make sure v2 is doing it the right way. Yes, this might lead to some extra work now, but we think it's worth it to have an API sooner than WP-API is going in WordPress core, with all the goodies we've got coming up that are now waiting on the API. :)
I agree with @rmccue here, using
Maybe this is far fetched, but what about having separate calls for the meta values, or is that really overthinking it now? If we're going with
Yes, but please give these a
Not for me, but I'd like @mikejolley to confirm that we can bump the required version for WooCommerce 2.1 to WordPress 3.7. I'm not seeing any issues with it, other than that we need to do some compatibility testing.
We agreed to not add any create functions for now, since the API will not support this in the initial release. Possibly looking into this for WooCommerce 2.2, depending on what is going to happen to WP-API after WordPress 3.8 gets released and what the roadmap of WP-API is gonna be. We'll see how this fits then. |
Getting to your other questions now, @maxrice:
I think this really depends on how your store is handling orders and what your personal preferences are. Same goes with apps and other systems using the API later on. I say stick to any status by default.
That's probably best, right? Anything we need to think of when we do this?
Hmm, this is a tricky one. Having just a variation without its parent is pretty useless in most cases, but it feels more 'clean' to have just return the variation alone (maybe with a reference/id to the parent). Is there anything similar out there we can spy at, see how they are doing it? :)
Will it work what @rmccue suggested here?
I like this, seems fitting and in line with all the other things we've thought of.
I'm not that much into API's to feel comfortable answering these questions without knowing all the pros and cons. Can you give some more insight in this? Is it possible to have some of the more complex situations (I can imagine both result in some extra work) to be pushed to v2 of the API? |
I'll try to cover all the excellent feedback here, and update the original issue as well.
Yep, I think the class is really well suited to a standalone base class that handles routing and other misc. tasks, and then can be sub-classed to provide JSON or XML responses (especially since the XML class will need an array to XML method).
Indeed, I implemented with a custom authentication handler, although it required some edits to the filter to make it useful. I'd love to see the OAuth implementation have some more eyes on it and am happy to submit a PR to the WP-API repo when it's ready for authentication stuff :)
After discussing with @coenjacobs, we're going to add this as a top-level
I need to look closer at the
Yeah I saw that the WP-API resource classes (WP_JSON_Posts,etc) uses camelCase for method names and I'm assuming that's because of the legacy XML-RPC API uses similar naming. Since WC has no such baggage, I think adhering to the WP Coding Standards on method names makes sense for this. Overall having the WP-API code available has been a huge, huge help thus far and I really appreciate your feedback on the implementation.
The closest example I can find is Shopify's API which exposes a I think I lean more towards consistency in the response, since it'd be a PITA to have to account for receiving different information when you request a variation without first knowing that it's actually a variation. In this case, I like @rmccue's idea to include the full variation information and then embed the parent product in it's own attribute. That response will be the most complex one for the entire API.
I can imagine some scenarios where you'd want one API key that allowed READ permission and another that allowed WRITE permission, and both run under the security context of your WP user. The big issue here is that if you allow multiple keys per user, you then have to store them as user meta (unless you do some hacky approach like suffixing the user meta keys with 1, 2, 3, etc.), which means in order for the API to lookup a WP user given their public key, it has to find every user with that specific meta, unserialize it, and then loop through until it finds a match. This won't scale well if a site has a lot of users with API keys, but maybe we can assume most site's will only have a handful of users? @thenbrent I know you've got experience with serialized user meta ;) any input on this? Either way, it's something we need to decide on in the v1 because it affects how we're storing the keys and it'd be nice to avoid changing our data structure for the key storage in the future if possible. As for hashing the secret keys, it's mostly a question of convenience. Obviously once it's hashed, we can't display it to the user again, so they'd have to re-generate their secret key if they lose it. I did find that Amazon AWS (perhaps the largest implementation of API authentication over plain HTTP) is now hashing and storing secret keys, as they cannot display your secret key once you've generated and saved it. While secret keys aren't exactly the same as passwords, they could still be pretty damaging if compromised, e.g. an attacker could delete all orders, or modifying existing ones, etc. For this reason alone it might be worth hashing. |
The main issue is that it makes search/retrieval a pain. If you just need to store multiple |
Also @maxrice, this looks amazing. |
Based on WP_JSON_Server, this class add response handling based on endpoint suffixes (.json or .xml) or the ACCEPT header. It also removes some unneeded functionality and renames filters so as to not conflict with users who may have WP-API installed already. Finally, instead of no authentication required by default, authentication is always required unless specifically disabled via filters.
@kloon Yeah that part was done prior to some other updates, so really it should use |
Hi, I am using WooCommerce by WooThemes version 2.0.20. How do I add the REST API to an existing website? |
@jmawebtech You don't, until WooCommerce 2.1 goes out. The currently builds are not stable yet to be used on a live website. The final is going out in January 2014. |
@maxrice Finished up the API wrapper library https://github.com/kloon/WooCommerce-REST-API-Client-Library |
@kloon legend! I'll hopefully get a chance to play with that before the week's out. :) |
@kloon just did some initial testing, looks really nice. The OAuth stuff looks like it wasn't as bad as I imagined to work with, so that's a big plus :) |
Hi, Has WooCommerce 2.2 and this API been released? Do you have a final release date for 2.2 and this API? |
@jmawebtech the API will be in WC 2.1. Extension developers have been told to ensure their extensions are WC 2.1 compatible by 20th Jan, so I imagine the WC 2.1 release date will be a few weeks after that. |
Do you have a 2.1 beta available with the API I can use? Sent from my Windows Phone From: Brentmailto:notifications@github.com @jmawebtechhttps://github.com/jmawebtech the API will be in WC 2.1. Extension developers have been told to ensure their extensions are WC 2.1 compatible by 20th Jan, so I imagine the WC 2.1 release date will be a few weeks after that. — |
I get a 404 error when I visit the site: http://localhost/wordpress/wc-api/v1 . I enabled the API from the WooCommerce admin. Am I looking at the right spot? |
I went to http://localhost/wordpress/index.php?wc-api-route=/wc-api/orders/count and I get this error: {"errors":[{"code":"woocommerce_api_authentication_error","message":"Invalid authentication method"}]} Is oAuth available yet? |
@jmawebtech do you have default permalinks enabled? If you access it over SSL you don't have to use OAuth :) see temporary documentation here |
I don't believe so. What are the default permalinks? Please send me a URL rewrite rule. |
@jmawebtech you'll want pretty permalinks enabled |
Alright, I have that part now. I get this error: Consumer Key is invalid. My site is on SSL. I sent Authorization in the header with USERNAME:PASSWORD Authorization: Basic xxxxx . Do I need another value? Do I need to create a special API user name and password? Request GET https://jmawoocommercetest.azurewebsites.net/wc-api/v1/order/count HTTP/1.1 Response HTTP/1.1 401 Unauthorized {"errors":[{"code":"woocommerce_api_authentication_error","message":"Consumer Key is invalid"}]} |
Hi, I figured it out. I went to Users, scrolled to the bottom, and generated an consumer key and a secret. |
Hi, maxrice. Are this available endpoint to retrieve available downloads for the given customer in API? |
amazing project! Almost exactly what i need. Maybe you will implement something to create products? |
can I get list of categories through api ? |
@drosanda product categories? nope -- if you want to see this in the next version, open an issue for it so everyone can discuss :) |
Im having a problem, i want to display all my products lets say 426, but it will just display 4 of it.. |
I am having the same problem. When I try to display all products it only displays the first 11. After that I receive the following error: Notice: Undefined offset: 12 in /home/rmpxro96/public_html/ on line 62 |
@andreicyr is that the only error in your PHP error log? Does it reference a specific file? |
Is it possible to Create An Order using GET method? |
@krrishnajee nop, you must use POST: http://woothemes.github.io/woocommerce-rest-api-docs/#create-an-order |
This is the initial version of the REST API, #3175. It is still very experimental but ready for feedback and testing.
Authentication is handled two ways. First, if Force Checkout SSL is enabled, the API index declares support for SSL and API requests can be easily authenticated by passing the consumer key and secret key as HTTP Basic Auth username/password.
If SSL is not available, API requests must be signed according to the OAuth 1.0a spec, implemented as "one-legged" OAuth. This means that every request is signed and authenticated instead of the consumer receiving a token for future use. While it's somewhat of a pain to implement, it's the only way to ensure requests are secure when using plain HTTP.
To test/review, pull this branch and comment out or remove this filter so you don't have to authenticate. All endpoints are at
http://example.com/wc-api/v1/
. I'll update this list of endpoints as implementations are finished.Index
GET /
Orders
GET /orders
GET /orders/count
GET /orders/<id>
GET /orders/<id>/notes
Coupons
GET /coupons
GET /coupons/count
GET /coupons/<id>
GET /coupons/code/<code>
Customers
GET /customers
GET /customers/count
GET /customers/<id>
GET /customers/<id>/orders
Products
GET /products
GET /products/count
GET /products/<id>
GET /products/<id>/reviews
Reports
GET /reports
GET /reports/sales
Open Questions
GET /orders/count
Closed questions
This uses some code from the WP API project, mainly the WP-JSON-Server class. It makes routing and other response-related stuff outrageously easy. My only issue is that it couples a JSON response type very tightly to the routing, which makes it impossible for us to support XML-based responses.*
I think the routing handling could be refactored into a base class, and two sub-classes created, one to handle JSON and the other to handle XML. This would also make it easier to make the entire class more WooCommerce-specific, which prevents any unexpected conflicts if a user is running the WP-API as a plugin on their server, or if it's merged into WP core.How should order/coupon/product/customer meta be implemented?I like the idea of awill be implemented as resource-specificmeta
attribute for each of the response objects that can be enabled with something like?include_meta=true
or similar in the request.product_meta
attributes. Clients will indicate they want meta returned in response by includingmeta=true
infilter
parameter.Should get_json_url() and json_url() be prefixed?yes and refactored to return canonical WC-API URL.Global functions to create orders/products would be very helpful in reducing code duplication. Order/Product clones of woocommerce_create_new_customer would be perfectcreating orders and products via the API will be pushed to WC 2.2orders will include any status by default/orders
returns orders with any status by default, should default be processing/completed instead?should totals be cast to string so they're string quoted in json response?totals will be cast as stringWhen requesting a variation ID, should the response include only the variation product? or should it include the variable parent product, and the requested variation listed as the only variation?variations will return the same set of data as a regular product, with the parent variable product data included as a top-level attribute.Should thea new endpoint will be added/coupons
endpoint have a custom parameter for getting coupons by coupon code? Theq
parameter searches both code/description alreadyAPI keys are currently 1 per user (and API requests run under the WP permissions of that user), should we support multiple keys per user?API keys will be serialized into a single user meta entry to support multiple keysshould API secret keys be hashed prior to storage? This would prevent accessing the plaintext key again after it's displayed + storedsecret keys cannot be hashed because we need them in plaintext to calculate the OAuth signature for plain HTTP requestsWe need to require WP 3.7 in order to allow date filtering, any obvious problems with this? It degrades gracefully for pre-3.7 versionsWC 2.1 will bump the minimum WP version required to 3.7Since the v1 API won't support creating products or orders, should theDELETE endpoints will be removed and added along with PUT/POST in 2.2DELETE
method be removed for those endpoints as well?Should responses be consistent with use of a blank string ornull
for non-values? currently it's a mixnull
will be used for values that aren't setShould we rename legacynot in 2.1, maybe 2.2wc-api
endpoint towc-ipn
to prevent confusion with REST API?Todos
General
current_user_can
checks)filter_response_fields()
method should support specifying sub-fields, e.g. billing_address.country (completed in SHA: maxrice@3130369)q
,limit
,offset
and date filters behind brackets, likeGET /orders?filter[q]=search
(completed in SHA: a13a95e)filter
parameter, likeGET /orders?filter[meta]=true
(completed in SHA: maxrice@48e8363)Products
GET
method (completed in SHA: maxrice@674ea42)Customers
created_at_min
/created_at_max
withpre_user_query filter
using this (completed in SHA: maxrice@1f5db98)Coupons
GET /coupons/code/foo
endpoint (started in SHA: maxrice@a13a95e, completed in SHA: maxrice@5ab8e08)Reports
GET
for Sales Report method (completed in SHA: maxrice@c1854b2)Authentication
Settings
TBD (in order of importance)
Implement API request logging - probably a new tab in Reportssee Add request logging to REST API #4159Orders - Implementsee Add PUT/POST/DELETE methods to Orders API endpoint #4160PUT
method, particularly for updating status of an orderCustomers - Implementsee Add PUT/POST/DELETE methods to Customers API endpoint #4162POST
andPUT
methodsCoupons - Implementsee Add PUT/POST/DELETE methods to Coupons API endpoint #4163POST
andPUT
methodsImplement XML parsing/generationsee Add XML output for REST API #4165Products - Maybe implementsee Add PUT/POST/DELETE methods to Products API endpoint #4164PUT
methodAllow un-authenticated access tosee Allow unauthenticated access to Products API endpoint #4166GET /products
- this needs to be very carefully tested to make sure we don't accidentally expose sensitive information. We might even consider an entirely new endpoint so it can be sandboxed.Consider allowing multiple API keys per user, probably don't need to bother since it's easy enough just to create a new WP user and assign keys that way.should wait on user feedback before implementing thisDocumentation