chatventure/swyf-sdk

用于与Swyf API通信的库，实现分面浏览和产品搜索。

维护者

详细信息

github.com/Chatventure/swyf-sdk

主页

源代码

问题

安装: 102

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 4

分支: 2

开放问题: 0

dev-master 2012-10-04 10:12 UTC

Requires

Apache-2.0 d363b31b33c1608068efc1a9d2bf68e52633cb74

  • Jasper van Wanrooy <jvanwanrooy.woop@swyf.com>

sdkswyf

This package is not auto-updated.

Last update: 2020-08-07 17:47:00 UTC

README

Swyf官方SDK，用于实现分面浏览和产品搜索。当您将浏览应用集成到您的网站时，可以使用此API。

Swyf API

API基于REST原则构建

  • 尽可能使用HTTP标准。
  • 所有请求都是无状态的。
  • URI类似于目录。
  • 输出类型可以是json或xml。

HTTP方法

根据账户类型，API支持以下HTTP请求方法：

  • GET /resource
    返回指定资源类型的对象列表。可选地，可以使用一些查询参数来应用过滤。
  • GET /resource/:resource_id
    根据资源类型和id返回对象。
  • POST /resource
    创建给定资源类型的新对象。当对象成功创建时，将返回状态码201，并在Location头中包含创建的对象。
  • PUT /resource/:resource_id
    POST /resource/:resource_id?_method=PUT
    根据资源类型和给定的id更新对象。
  • DELETE /resource/:resource_id
    POST /resource/:resource_id?_method=DELETE
    根据资源类型和给定的id标记对象为已删除。

格式化

API支持JSON（默认，首选）和XML。

从API检索信息时，有两种方式可以指定格式。当两种方式都使用时，查询参数具有最高优先级。

  1. Accept HTTP头
    这可以由每个请求传递。值可以是application/json或application/xml。SDK自动且仅支持JSON。
  2. _format 查询参数
    此参数可以始终附加到API URL。可能的值是：json或xml。

在更新或创建对象时，应使用Content-Type HTTP头。可能的值与Accept头相同。

认证

当然，所有对API的请求都需要认证。这是通过一个具有秘密的应用程序实现的。需要通过在每个请求中添加X-API-Application和X-API-Secret HTTP头来提供这些信息。这当然是在Swyf SDK中实现的。

资源类型

可以从API检索一些资源，其中一些甚至可以过滤

  1. 产品
  2. 浏览册
  3. 商店
  4. 用户账户

API路由

上述资源类型可以一起使用，以实现端点的过滤。端点定义为URL的最后一部分。考虑以下API URL：https://api.shopwithyourfriends.com/api/v1/lookbook/8734/product。它由以下部分组成

  • https://：协议始终是SSL；
  • api.shopwithyourfriends.com：主机名始终固定；
  • /api/v1：固定前缀用于版本控制；
  • /lookbook/8743：根据该特定lookbook过滤此请求；
  • /product：具体的API端点；

系统定义了以下路由和过滤器；

  • /product 返回包含以下键的多个产品列表；

    • product_id：标识符；
    • name：产品的名称；
    • api_url：获取关于此产品更多数据的url；
    • image_small：小图像的url；
    • image_medium：中等图像的url；
    • image_large：大图像的url；
    • deeplink_buy_url：用于购买产品的url；
    • price_formatted：预格式化的价格；
    • from_price_formatted：预格式化的起始价格（在促销的情况下）；
    • shop_currency：商店使用的ISO货币；

    以下过滤器可用；

    • limit：限制查询（默认为10）；
    • offset：给查询提供偏移量（默认为0）；
    • query：搜索查询（仅字符串）；
    • category：可以是逗号分隔的字符串或数组；
    • shop：可以是逗号分隔的字符串或数组；
    • brand：可以是逗号分隔的字符串或数组；
    • price：可以是逗号分隔的字符串或数组；
    • discount：可以是逗号分隔的字符串或数组；
    • sort：可以有以下值：relevance、price-asc、price-desc、popularity、date 注意，默认为date，使用query过滤器时，默认为relevance。

  • /product/:product_id 返回一个包含以下键的单个产品；

    • product_id：标识符；
    • name：产品的名称；
    • api_url：获取关于此产品更多数据的url；
    • image_small：小图像的url；
    • image_medium：中等图像的url；
    • image_large：大图像的url；
    • deeplink_buy_url：用于购买产品的url；
    • price：价格的浮点表示；
    • price_formatted：预格式化的价格；
    • from_price：起始价格的浮点表示（在促销的情况下）；
    • from_price_formatted：预格式化的起始价格（在促销的情况下）；
    • shop_name：商店的名称；
    • shop_name_normalized：商店的名称，适用于url；
    • shop_currency：商店使用的ISO货币；
    • brand：品牌的名称；
    • brand_normalized：品牌的名称，适用于url；

  • /product/:product_id/shop 返回一个格式与/shop相同的单个商店；

  • /product/:product_id/lookbook 返回一个格式与/lookbook相同的列表；

  • /lookbook 返回包含以下键的多个lookbook列表；

    • lookbook_id：标识符；
    • api_url：获取关于此lookbook更多数据的url；
    • title：lookbook的标题；
    • description：lookbook的描述；
    • image_small：小图像的url；
    • image_medium：中等图像的url；
    • image_large：大图像的url；
    • created_at：创建日期和时间；
    • total_price：总价格的浮点表示；
    • total_price_formatted：预格式化的总价格；
    • total_price_currency：jpx使用的ISO货币；

    以下过滤器可用；

    • limit：限制查询（默认为10）；
    • offset：给查询提供偏移量（默认为0）；
    • query：搜索查询（仅字符串）；
    • tags：可以是逗号分隔的字符串或数组；
    • sort：可以有以下值：relevance、popularity、date 注意，默认为date，使用query过滤器时，默认为relevance。

  • /lookbook/:lookbook_id 返回一个与/lookbook相同的格式的单个lookbook；

  • /lookbook/:lookbook_id/product 返回一个与/product相同的格式的列表；

  • /shop 返回包含以下键的多个商店列表；

    • shop_id：标识符；
    • api_url：获取关于此商店更多数据的url；
    • name：此商店的名称；
    • normalized_name：商店的名称，适用于url；
    • description：商店的描述；
    • target_gender：商店的目标性别；
    • locale：商店的区域设置；
    • currency：此商店使用的货币；
    • image：商店标志的url；
    • shop_url：商店主页的url；
    • return_time：最大允许退货时间。
    • return_free: 返回是否免费（true或false）
    • return_address: 客户可以退货的地址
    • return_money_back: 退货后退款（true或false）
    • delivery_time: 常规配送时间
    • payment_method: 接受的支付方式列表
    • delivery_costs: 常规配送费用

  • /shop/:shop_id 以与 /shop 相同的格式返回单个商店。

错误

API可以返回两种类型的错误：认证和请求。平台上的所有错误都有一个三位数代码、一条消息和一个HTTP响应代码。

认证错误

错误代码HTTP状态错误消息
100401认证失败
101401凭证无效
102403不允许在%s上%s。
103403不允许访问id为%s的对象%s。

请求错误

错误代码HTTP状态错误消息
200500请求失败
201501请求的对象未知：%s。
202404id为%s的对象%s不存在。
203501请求的对象无效。
204405请求的方法无效：%s。
205400方法%s需要一个对象id，但未指定。
206400方法%s不需要对象id，但已指定：%s。
207400某些参数缺失：%s。
208500插入数据失败：%s。
209500更新数据失败：%s。
210500删除数据失败：%s。
211404id为%s的对象%s未激活。
212400参数'%s'的值'%s'无效。
213400在%s中已存在具有社交网络ID %s的SnUser。
214400找到的参数多于所需。
215400方法%s在对象%s上只能通过%s调用。
216400对象%s上的方法%s未实现。
217403用户%s的UserAccountSetting已存在。

Swyf PHP SDK

Swyf PHP SDK是一个非常小的包装器，它处理Swyf API提供的所有通信、编码、认证和URL处理。该库是开源的，鼓励每个人提交错误报告、完成文档等。

SDK的入门相当简单

  1. 从团队那里获得应用程序和密钥。
  2. 确保您有基于psr-0的自动加载程序，或者已安装composer。
  3. 初始化一个new Swyf_Api($application, $secret)对象。
  4. 使用get、post、put、delete执行API请求。

异常

所有API请求都可以抛出三种类型的异常。类型包括

  • Swyf_Api_Exception
    用于API内部错误的异常，如API文档中所述。代码和消息相匹配。
  • Swyf_Http_Exception
    用于API请求构建中出现的所有问题。
  • Swyf_Http_Exception_Curl
    用于cURL模块返回的所有错误，可以是系统错误也可以是请求错误。

示例代码

以下代码示例解释了如何使用API。我们首先包含自动加载程序并初始化Swyf_Api。然后设置基本URL，我们就可以开始调用API了。

<?php
ini_set('display_errors', 'On');
error_reporting(E_ALL);

include_once 'vendor/autoload.php';

$api = new Swyf_Api('jpx-JPXID', 'JPXSECRET');
$api->setBaseUrl('https://api.shopwithyourfriends.com/api/v1/');

$res = $api->get('product', array(
	'FILTER_NAME' => array(
		FILTER_VALUE
	),
	'FILTER_NAME' => FILTER_VALUE
));
?>

结果

结果以PHP数组和对象返回，下面的JSON是为了可读性。

{
	data: {
		items: [ //contains the requested items
			{ … }, 
			{ … }
		],
		total_hits: TOTAL_RESULT_COUNT,
		facets: { //contains available facets
			FACET_NAME : {
				other_items_count : 0,
				items : [ //contains available filters
					{
						items : [ //contains available sub filters
							{
								normalized_name: NORMALIZED_NAME,
								count: NUMBER_OF_ITEMS_WITH_FILTER,
								is_selected: false,
								is_child_selected: false,
								display_name: DISPLAY_NAME,
								type: FACET_NAME,
								parent_normalized: PARENT_NORMALIZED_NAME,
								is_parent_selected: false
							},
							{ ... }
						],
						normalized_name: NORMALIZED_NAME,
						count: NUMBER_OF_ITEMS_WITH_FILTER,
						is_selected: false,
						is_child_selected: false,
						display_name: DISPLAY_NAME,
						type: FACET_NAME,
						parent_normalized: null,
						is_parent_selected: false
					},
					{ ... }
				]
			},
			{ ... }
		}
	},
	paging: {
		prev: null,
		next: 'https://api.shopwithyourfriends.com/api/v1/product?category=&query=&sort=&limit=10&offset=10'
	}
}