The latest version of Magento (1.7rc1 right now) has support for oAuth authenticated REST APIs, yippee! In this post I’m going to run through the technical aspects of setting up the Magento oAuth and making your first Magento REST API call.
I’m presenting on APIs during the technology track at the Magento Imagine conference on Tuesday (If you’re reading this, and you’re at the conference, I hope to see you there!). In my talk I’ll cover interesting uses and benefits of the REST API but won’t have time for a big fully worked example. This post details the finer points of actually using these APIs which is a bit too low-level to cover, so this will be extra-for-experts homework for those that want to have a play around with REST after the talk.
There are basically 3 steps to running your first REST API call in Magento.
0) Get an oAuth client tool
Let me say right at the outset, debugging oAuth issues is one of those crappy problems in web development, like character encoding and object aliasing, it is a real pain when it doesn’t just work™ and you’re going to want a good toolset if things go sour.
In my examples below I’m using the ruby oAuth library because it’s clean simple and works well. There’s something similar for python and PHP, so choose your poison. To set up the ruby one, assuming you have ruby already, just run:
sudo gem install oauth
Right, now you’re at the start line.
1) Set up the Magento server
You need to configure the role for the oAuth, specify the attributes and lastly create a consumer.
For the purposes of this tutorial to keep it simple, you can just grant the customer all the attributes and permissions – but if you were being cautious, you’d pick and choose to suit your needs.
The roles are similar to the old web service roles, they allow you to select which permissions a type of REST user has. The attributes allow you to select which entity attributes appear in the response. Customers probably would not see cost, for example.
Now, make your consumer, and take a note of the consumer key and secret.
(eek, the fields are disabled, not readonly – I used firebug to copy-paste, or you can view source.)
Now the server is setup – you should have the roles, attributes and consumer configured, and for testing you’ll need a test customer account too. Now we are ready for the actual oAuth requests.
2) Get the oAuth tokens
The oAuth dance, oops I mean dance is not as fun as it sounds – but when it works, it’s a painless way for a web service client to be granted permission to call a service, without exposing any user credentials, which is great for security.
Here’s an example of that authorization process:
oauth \ --verbose \ --query-string \ --consumer-key v484mnii2jyswedm6uo2cfcjay7uy49snws \ --consumer-secret koay6845che7giy5lr17gnrhckkbhf8h5 \ --access-token-url http://www.yourstore.com/magento/oauth/token \ --authorize-url http://www.yourstore.com/magento/oauth/authorize \ --request-token-url http://www.yourstore.com/magento/oauth/initiate \ authorize Server appears to support OAuth 1.0a; enabling support. Please visit this url to authorize: http://www.yourstore.com/magento/oauth/authorize?oauth_token=ey6fokp0pbzwr1016eb528y5xw1ak5ji Please enter the verification code provided by the SP (oauth_verifier): YOUR_CODE_HERE Response: oauth_token_secret: g9kyz8c7zv868d58eav1muih3gxvq763 oauth_token: aqvlfv9tuexn0mqiydgkaff4ixxg8743c
The authorize url you visit will ask you to log in (as a customer, unless you use the admin authorize url instead:
/admin/oAuth_authorize). You’ll login and then authorize the client like this.
After a successful login and authorize you should see this dialog, and you’ll copy the verifier code into the oauth commandline to complete the process.
3) Make the API call
You’ll want to use the oauth command line tool (or your preferred tool) to create the oAuth signature and generate the URL to play around with. Here’s an example using the
debug option, it’ll give you an idea of what’s going on, and displays the copy-pastable URL you’ll use in the next step:
oauth \ --consumer-key v484mnii2jyswedm6uo2cfcjay7uy49snws \ --consumer-secret koay6845che7giy5lr17gnrhckkbhf8h5 \ --token aqvlfv9tuexn0mqiydgkaff4ixxg8743c \ --secret g9kyz8c7zv868d58eav1muih3gxvq763 \ --uri http://www.yourstore.com/magento/api/rest/products \ debug
Note: the URL I am going to use is
http://www.yourstore.com/magento/api/rest/products – but you can see all the possible urls in the api2.xml files in the core code. For example here’s a snippet from the catalog api2.xml that shows some of the path patterns:
<routes> <route_entity> <route>/products/:id</route> <action_type>entity</action_type> </route_entity> <route_entity_with_store> <route>/products/:id/store/:store</route> <action_type>entity</action_type> </route_entity_with_store> <route_collection> <route>/products</route> <action_type>collection</action_type> </route_collection> ... </routes
You can choose your favorite HTTP client (the URL will work in any browser), I’ll use
curl below, for demonstrative purposes. Grab the ‘OAuth Request URI’ from the output above and use it like I do below.
Getting a list of products in JSON (JSON is the default, you can omit the
Accept header if you want):
curl \ -H "Accept: application/json" \ "http://www.yourstore.com/magento/api/rest/products?oauth_consumer_key=tydkxii2jyswedm6uo2cfcjay7uy0crws&oauth_nonce=HWJHh83HKeJnsFahdQxye52dapt8F7bswrnLcAYjsy&oauth_signature=%2FkHLJKs9W3fmWRVxAPrd8R7LHDs%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1335162435&oauth_token=aqvlfv9tuexn0mqiydgkaff4ixxgs58s&oauth_version=1.0"
Getting a list of products in XML (set the
Accept header for XML):
curl \ -H "Accept: application/xml" \ "http://www.yourstore.com/magento/api/rest/products?oauth_consumer_key=tydkxii2jyswedm6uo2cfcjay7uy0crws&oauth_nonce=HWJHh83HKeJnsFahdQxye52dapt8F7bswrnLcAYjsy&oauth_signature=%2FkHLJKs9W3fmWRVxAPrd8R7LHDs%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1335162435&oauth_token=aqvlfv9tuexn0mqiydgkaff4ixxgs58s&oauth_version=1.0"
All going to plan you should see some JSON or XML output that represents your products, phew!
Lastly I’d like to say ‘Thanks’ to Lindy, Baruch and Vinai from Magento for their help getting started with an example test harness (and rushing out a 1.7 WS-I bug fix for me!). There’s precious little documentation currently, but hopefully this post will help others get started.
For PHP coders interested, here’s the test harness courtesy of Lindy you can dig into a bit more. (Note: all copyrights etc to Magento)
And that’s it, you can now make your own REST calls and dream up cool and interesting ways to allow customers and admins to access Magento store data! I’ll cover some possibilities for this cool new technology in my talk on Tuesday, hope to see you all there – I’ll only accept inexplicable tigers and/or chickens in your hotel room as an excuse!