For those that don’t know, Magento added REST server functionality since version 1.7.0 < .
Before that, Magento had SOAP and XML-RPC server implementations which are also implemented in newest Magento versions.
I have to admit that even I had a lot of experience with Magento SOAP web services, it took a little bit time even for experienced developer like me, to figure out how Magento REST is implemented and how to take advantage of it. The biggest reason for that is the lack of official documentation.
Yes, we have some documentation about Magento REST on this URL:
Introduction to REST API,
but this still does not explain a lot of things that we need to know in order to properly use the features that Magento offers with its new oAuth and REST server.
Just a small notice for newbies: This article is not intended to explain the basic things about: “What are oAuth and REST?”, “What are the web services and how they work?”. I assume that every reader is familiar with that. If not, stop reading and return here with some basic knowledge on that.
We could divide Magento REST functionality into the two rounded up units:
- Magento oAuth server and functionality
- Magento REST server and functionality
In order to consume Magento REST services, we MUST use oAuth authentication as this is the only currently implemented auth adapter for Magento Api2.
If you navigate to System -> Web services from your Magento admin dashboard you can see available options for REST and oAuth:
- REST roles
- REST attributes
- REST oAuth consumers
- REST oAuth authorized tokens
- REST My Apps
Let’s try to explain each of those in order to get the better understanding of REST api implementation in Magento:
REST roles
We have three basic types of REST consumers that can access Magento Api2 resources:
- Guest (Non-Logged-In frontend user)
- Customer (Logged-In frontend user)
- Administrator (Logged-In backend user)
This gives us possibility to define different roles for accessing REST resources for each user type separately.
For example, customer could have permission to access his own account data and administrator could have permission to access any customer account, while Guest user could not have permission to customer resources at all …
Also, for each customer type, we can fine tune permissions not just for specific REST resource but even for specific action on this resource: Create, Retrieve, Update, Delete.
Possible actions depending on customer type are defined along with the other Api2 configurations inside api2.xml config files in Magento modules, but this configuration is beyond the scope of this article (it could be described in some future article on “How to create Magento REST resource” or something).
REST attributes
In Magento REST implementation, we have two logical possible actions on each resource’s attributes :
- Read action
- Write action
Each REST resource can have own attributes and depending on api2.xml configuration for specific resource, for each REST role, we can allow read/write operation for each specific attribute. To make is simpler to understand:
Example:
Customer address is Resource.
Customer address has attributes:
- Street
- City
- ZIP
- Country
In Customer Address extension’s api2.xml file could be defined available options depending on user type like this:
- Admin user has option to read and write attributes: Street, City, ZIP and Country from Customer Address resource.
- Customer has options to read attributes Street, City, ZIP and Country from Customer Address resource.
- Guest has option to read only Street attribute from customer address etc.
This options depending for each role (Administrator, Customer, Guest) will appear in Magento admin area under Attributes configuration screen for specific role and administrator needs to check the attributes and operations (read, write) that he wants to allow on specific resource:
REST oAuth Consumers
REST oAuth consumers are third party applications that can consume REST services from Magento.
REST oAuth authorized tokens
When REST client authorize against Magento oAuth server, its token will be added under authorized tokens and client will have access to allowed resources in Magento using that token.
REST My Apps
This area is just current Logged-in Admin user – specific.It contains listed Applications that are authorized against Magento oAuth just for current admin account.
Note: Like admin user here, also every frontend customer – user under “My Account” have section “My Apps” where he can manage his authorized Apps.
I hope that I explained succesfully some basic things about Magento REST and oAuth options that we have available through admin area. Of course, this is just a beginning, we still need to explain how to configure your Magento REST and oAuth services and also how to consume REST services from php, but I will leave that for some of my next articles. 🙂
