Web API Plugin for nopCommerce (v. 3.60)

List of Content About the plugin .............................................................................................................................................. 3 Installation and configuration ......................................................................................................................... 3 Web API - description ...................................................................................................................................... 3 Examples.......................................................................................................................................................... 5 Example for CATEGORIES ............................................................................................................................ 6 1.

GET all categories ............................................................................................................................ 6

2.

GET category by id ({id=1}) .............................................................................................................. 6

3.

POST (update) new category ........................................................................................................... 6

4.

PATCH (partial update - the client specifies just the properties to update) ................................... 7

5.

PUT (update category)..................................................................................................................... 7

6.

DELETE category .............................................................................................................................. 8

Examples for CUSTOMERS........................................................................................................................... 8 1.

GET customer (with expand options) .............................................................................................. 8

2.

PUT (add) address for customer (which exists in table Addresses) ................................................ 8

3.

DELETE address for customer (reference) ....................................................................................... 9

4.

PUT (add) role to customer ............................................................................................................. 9

5.

DELETE role for customer (existing role) ......................................................................................... 9

Examples for PRODUCTS ........................................................................................................................... 10 1.

PUT (add) tag for product (existing tag) ........................................................................................ 10

Example for ORDERS ................................................................................................................................. 10 1.

GET OrderDate .............................................................................................................................. 10

Example for IMAGE ................................................................................................................................... 10 1.

Prepare Picture model................................................................................................................... 10

2.

Prepare ProductPicture model ...................................................................................................... 11

Clear Cache (version 3.70) ......................................................................................................................... 12 Enabling Cross-Origin (version 3.70) ......................................................................................................... 12 Cross-Origin Example ................................................................................................................................ 12 Show data without value (count option) .................................................................................................. 15 Show all methods used ............................................................................................................................. 15

2 nop4you.com

About the plugin Plugin Web API for nopCommerce (version 3.60) gives an access to business data stored in nopCommerce database. It has been built in ASP.NET Web API and the OData provider. More info about Web API can be found on http://www.asp.net/web-api. Note: User should be familiar with nopCommerce database structure.

Installation and configuration First of all, the Web API plugin has to be installed on the nopCommerce. Only registered customers (in nopCommerce) with both keys (public and secret key) have got an access to the API. Web API plugin uses customer roles and rights to authorize client (for getting/updating data) -> based on ACL in nopCommerce. Register customer for Web API (user should exist in nopCommerce as a registered user). Go to Plugin List -> (on WebAPI plugin) Configure.

Web API - description Plugin provides following methods:  

GET – queries database (like a select); POST – insert data to database;

3 nop4you.com

 

PUT – updates data in dataset (all fields are required); PATCH (recommended update) – updates data in database (only do-not-allow-null fields in database are required).

Data model (metadata - i.e. structure and organization of all the resources) can be found under following link: http://yourstore.com/odata/$metadata (Request Header is required). Web API client can use OData options (like $filter, $top, $select etc.) and Web API specific options. More can be found on http://www.asp.net/web-api. Paging is required for querying multiple records. It can be done with OData $skip and $top. Code page: Request body needs to be UTF8 encoded. Request Header is required when client is calling WebAPI. Request HTTP header fields: Field

Is required

User-Agent Accept Accept-Charset Content-Type and Content-Length Content-MD5 Authorization

Optional Required Required Conditional

PublicKey

Required

Optional Required

Example/Description Short description of the API consumer Example for JSON: 'application/json, text/javascript' Always UTF-8 Necessary for the methods POST, PATCH, PUT, if new data is send via the HTTP body. Example: 'application/json; charset=utf-8' Only for methods POST, PUT The authorization schema and the HMAC signature. The schema is Basic. Example: 'your_email:Signature' is converted to base64. Example how to prepare signature: blow The public key of the customer, ex. 9cbc46ab0289979b3af3b96f532fad44

Example 1: How to prepare signature:

private string Signature() { string publicKey = YourPublicKey; string secretKey = YourSecretKey; if (String.IsNullOrWhiteSpace(secretKey) || String.IsNullOrWhiteSpace(publicKey)) return ""; string signature; var secretBytes = Encoding.UTF8.GetBytes(secretKey); var valueBytes = Encoding.UTF8.GetBytes(publicKey); using (var hmac = new HMACSHA256(secretBytes)) { var hash = hmac.ComputeHash(valueBytes); signature = Convert.ToBase64String(hash); } return signature; } string authInfo = Convert.ToBase64String(Encoding.Default.GetBytes( YourMail + ":" + Signature()));

4 nop4you.com

Result: authInfo = YWRtaW5AeW91cnN0b3JlLmNvbTpjUGZzeC9GaWRCbE9TRzZGUVAvei9pVGt2RnNhMWNJaTY5ZDBKekMxWVh JPQ==

Examples Examples (based on sample application) show how to build JSON client app. It can be downloaded from http://nop4you.com/WebApi.zip This is a sample application with source code to get/put/post/patch and delete request to your store using format JSON.

Methods:     

GET - Gets data or Get by Id - ({Id}); POST - Adds new data; PUT - Updates data ({Id}); DELETE - Deletes data ({Id}); PATCH - Updates data ({Id}) (recommended).

URL (first part): URL your store (example: http://nop4you.com) URL (second part): odata/ENTITY_TYPE({id})

URL example for calories (client want to get information about category with Id=1): odata/Category or odata/Category(1) (full address is: http://yourstore.com/odata/Category(1)) 5 nop4you.com

Client can use filters, for example: http://yourstore.com/odata/Category?$filter=Name+eq+'Books' http://yourstore.com/odata/Customer?$filter=Email+eq+'[email protected]' http://yourstore/odata/Customer?$filter=startswith(Name, 'A') Client can get columns, for example: http://yourstore.com/odata/Category(1)?$select=* http://yourstore.com/odata/Category(1)?$select=Id,Name Client can use select extensions (to get additional data joined with ‘main’ data), for example you client call customer with Id=1 and its addresses: http://yourstore.com/odata/Customer(1)?$expand=Addresses

Example for CATEGORIES 1.

GET all categories URL: http://yourstore.com/odata/Category REQUEST HEADER: Authorization: Basic YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R hT0VNPQ== > 2] >>> (24 - (i % 4) * 8)) & 0xff; u8[i]=byte; } return u8; }, parse: function (u8arr) { // Shortcut var len = u8arr.length; // Convert var words = []; for (var i = 0; i < len; i++) { words[i >>> 2] |= (u8arr[i] & 0xff)