Spree-e-commerce (Phần II) Xây dựng Web server trên nền tảng Spree

Như phần trước Phần I tìm hiểu về Spree - e - commerce chắc hẳn các bạn đã có cái nhìn cơ bản về ecommerce này, tuy nhiên sức mạnh của Spree không chỉ dừng lại ở đó, trong phần này mình xin tiếp tục giới thiệu một phần khác của Spree khá hay - biến Spree thành một Web server. Web server - khái niệm không quá xa lạ, có thể nói là xu hướng của hầu hết những hệ thống có sự kết hợp giữa Website và Mobile. Spree xây dựng API dựa theo chuẩn RESTful, cung cấp đầy đủ cho nhà phát triển một cách thuận tiện để truy cập dữ liệu có trong Spree.

Để bắt đầu tìm hiểu về API chúng ta cùng nhìn lại một số model cơ bản trong Spree và liên kết giữa chúng.

1. Address Lưu thông tin cơ bản về một đối tượng, chủ yếu phục vụ mục đích theo dõi đơn đặt hàng trong Spree, tuy nhiên có thể dùng kết hợp để lưu thông tin của user sử dụng spree_auth_devise. Address bao gồm những thông tin cơ bản sau:

• firstname: The first name for the person at this address.
• lastname: The last name for the person at this address.
• address1: The address’s first line.
• address2: The address’s second line.
• city: The city where the address is.
• zipcode: The postal code.
• phone: The phone number.
• state_name: The name for the state.
• alternative_phone: The alternative phone number.
• company: A company name.

Mỗi một địa chỉ sẽ được gắn với một quốc gia và tiểu bang tương ứng, trong trường hợp nước đó không có tiểu bang tương ứng thì có thể không liên kết với trường này. Việc này sẽ thuận lợi trong việc tính phí vận chuyển của đơn hàng cũng như đánh giá xem một đơn hàng có cần tính thuế ở các khu vực quốc gia khác nhau hay không.

2. Order

Lưu trữ tất cả thông tin của đơn đặt hàng của Spree bao gồm những thuộc tính sau.

• number: The unique identifier for this order. It begins with the letter R and ends in a 9-digit number. This number is shown to the users, and can be used to find the order by calling Spree::Order.find_by_number(number).
• item_total: The sum of all the line items for this order.
• adjustment_total: The sum of all adjustments on this order.
• total: The result of the sum of the item_total and the adjustment_total.
• payment_total: The total value of all finalized payments.
• shipment_total: The total value of all shipments’ costs.
• additional_tax_total: The sum of all shipments’ and line items’ additional_tax.
• included_tax_total: The sum of all shipments’ and line items’ included_tax.
• promo_total: The sum of all shipments’, line items’ and promotions’ promo_total.
• state: The current state of the order. To read more about the states an order goes through, read The Order State Machine section of this guide.
• email: The email address for the user who placed this order. Stored in case this order is for a guest user.
• user_id: The ID for the corresponding user record for this order. Stored only if the order is placed by a signed-in user.
• completed_at: The timestamp of when the order was completed.
• bill_address_id: The ID for the related Address object with billing address information.
• ship_address_id: The ID for the related Address object with shipping address information.
• shipping_method_id: The ID for the related ShippingMethod object.
• created_by_id: The ID of object that created this order.
• shipment_state: The current shipment state of the order. For possible states, please see the Shipments guide.
• payment_state: The current payment state of the order. For possible states, please see the Payments guide.
• special_instructions: Any special instructions for the store to do with this order. Will only appear if Spree::Config[:shipping_instructions] is set to true.
• currency: The currency for this order. Determined by the Spree::Config[:currency] value that was set at the time of order.
• last_ip_address: The last IP address used to update this order in the frontend.
• channel: The channel specified when importing orders from other stores. e.g. amazon.
• item_count: The total value of line items’ quantity.
• approver_id: The ID of user that approved this order.
• confirmation_delivered: Boolean value indicating that confirmation email was delivered.
• guest_token: The guest token stored corresponding to token stored in cookies.
• canceler_id: The ID of user that canceled this order.
• store_id: The ID of Store in which this order was created.

3. Product Lưu trữ thông tin về sản phẩm được bán trong Spree gồm những thông tin sau:

• name: short name for the product
• description: The most elegant, poetic turn of phrase for describing your product’s benefits and features to your site visitors
• permalink: An SEO slug based on the product name that is placed into the URL for the product
• available_on: The first date the product becomes available for sale online in your shop. If you don’t set the available_on attribute, the product will not appear among your store’s products for sale.
• deleted_at: The date the product is no longer available for sale in the store
• meta_description: A description targeted at search engines for search engine optimization (SEO)
• meta_keywords: Several words and short phrases separated by commas, also targeted at search engines

4. Một số model cơ bản khác

• Adjustments
• Calculators
• Inventory
• Payments
• Preferences
• Promotions
• Shipments
• Taxation

Trên đây chỉ là một số model cơ bản có trong Spree, hiện nay số lượng model core là 77 model, chi tiết về thông tin từng model các bạn có thể tìm hiểu ở đây List model Spree

Spree API được xây dựng theo chuẩn RESTful, kiểu dữ liệu trả về Json tiện lợi cung cấp cách truy nhập vào các đối tượng dưới đây:

• PRODUCTS
• PRODUCT PROPERTIES
• VARIANTS
• ORDERS
• LINE ITEMS
• CHECKOUTS
• PAYMENTS
• RETURN AUTHORIZATIONS
• SHIPMENTS
• TAXONOMIES
• ADDRESSES
• COUNTRIES
• STOCK LOCATIONS
• STOCK ITEMS
• STOCK MOVEMENTS
• ZONES

1. Một số luật các thiết bị đầu cuối cần tuân thủ khi sử dụng API

• Tất cả truy vấn thành công sử dụng API đều trả về kết quả 200.
• Yêu cầu tạo mới và update khi thành công sẽ trả về 201 hoặc 200 tương ứng.
• Cả hai yêu cầu trên nếu thành công sẽ trả về dữ liệu tương ứng từ Spree.
• Yêu cầu tạo mới hoặc update nếu không thành công sẽ trả về mã lỗi 422 và một list tất cả những lỗi gặp phải được định nghĩa bởi ActiveRecord.
• Yêu cầu xóa bản ghi sẽ trả về 200 và không có dữ liệu trả về.
• Yêu cầu lấy dữ liệu sẽ trả về danh sách các bản ghi được phân trang với số lượng từng trang là 25, có thể lấy dữ liệu của từng trang tương ứng nếu truyền theo số của trang.
• Nếu không tìm thấy dữ liệu API sẽ trả lại lỗi 404.
• Yêu cầu được Spree xác nhận là trái phép sẽ trả về 401.

STATUS: 404 NOT FOUND

{
  "error": "The resource you were looking for could not be found."
}

STATUS: 401 UNAUTHORIZED

{
 "error": "You are not authorized to perform that action."
}

STATUS: 401 UNAUTHORIZED

{
 "error": "Invalid API key ([key]) specified."
}

STATUS: 401 UNAUTHORIZED

{
 "error": "You must specify an API key."
}

2. X-Spree-Token Token để xác nhận truy cập là hợp pháp trong hệ thống, có thể tạo ra từ trang admin bởi url http://localhost:3000/admin/users/1/edit

3. Hai cách để gọi API

• Nếu muốn ẩn token API

 curl --header "X-Spree-Token: YOUR_KEY_HERE" http://example.com/api/v1/products.json

• Nếu muốn hiện token API

curl http://example.com/api/v1/products.json?token=YOUR_KEY_HERE

4. Spree API Products

Spree cung cấp đầy đủ API của một object gồm:

• Index

# list all
GET /api/v1/products
# List với params
GET /api/v1/products?page=2

• Search

GET /api/v1/products?q[name_cont]=Spree

• Show

GET /api/v1/products/1

• New

GET /api/v1/products/new

• Create

POST /api/v1/products?product[name]=Headphones&product[price]=100&product[shipping_category_id]=1

• Update

PUT /api/v1/products/a-product?product[name]=Headphones

• Delete

DELETE /api/v1/products/a-product

Ở đây mình xin demo một API New cho Product.

curl --header "X-Spree-Token: c502711582635b7f03e1dec3240b3c09a6e905c6ac02c8fa" http://localhost:3000/api/v1/products/new.json

Sẽ cho kết quả sau:

{
   "attributes":[
      "id",
      "name",
      "description",
      "price",
      "display_price",
      "available_on",
      "slug",
      "meta_description",
      "meta_keywords",
      "shipping_category_id",
      "taxon_ids",
      "total_on_hand"
   ],
   "required_attributes":[
      "name",
      "shipping_category",
      "price"
   ]
}

Các bạn có thể thấy Responce trả về đầy đủ thông tin cho thiết bị đầu cuối làm việc.

Ngoài những API có sẵn mà Spree cung cấp nhà phát triển hoàn toàn có thể custome chúng dễ ràng để phù hợp hơn với mục đích sử dụng. Với những gì Spree mang lại hoàn tòan có thể đáp ứng để trở thành một Web server hoàn thiện. Các bạn có thể tìm hiểu chi tiết về API Tại đây

Thanks for reading!!!