Welcome to LLZW’s documentation!¶

Authentication¶

This endpoint performs login action. After a successful login, the server will send you an authenticated COOKIE which represents all your privileges.

All your subsequent requests will inherit this identity.

HTTP Request¶

POST http://example.com/login

Request Parameters¶

Parameter	Type	Required	Default	Description
username	String	True		Your username
password	String	True		Your password

The response JSON structured like this:

{
  "responseId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "sucess": true,
  "data": null
}

Users¶

Registration¶

This endpoint registers a new user.

HTTP Request¶

POST http://example.com/api/v1/users/register

Request Parameters¶

Parameter	Type	Required	Default	Description
username	String	True		Username with pattern [a-zA-Z]w{5,50}
password	String	True		At least 1 upper case, 1 lower case, 1 digit and 1 symbol, min length = 8
email	String	True		min length = 5, max length = 100
phoneNumber	String	True		min length = 5, max length = 20
role	String	True		One of [‘ROLE_SELLER’, ‘ROLE_CUSTOMER’]
nickname	String	False	username	Nickname, max length = 100.
avatar	String	False		Image URL of avatar, which can be external URL or hash value of an uploaded image file

Response Parameters¶

Parameter	Type	Description
data	User	The created User object

Real Name Verification¶

This endpoint provides real name verification details for a specific user.

HTTP Request¶

PUT http://example.com/api/v1/users/realNameVerification

Request Parameters¶

Parameter	Type	Required	Description
identityType	String	True	One of [‘PRC_ID’, ‘PASSPORT’]
identityNumber	String	True	ID of specified document, min length = 1, max length = 20
firstName	String	True	min length = 1, max length = 20
lastName	String	True	min length = 1, max length = 20

Response Parameters¶

Parameter	Type	Description
data	User	The modified User object

Attention

Remember — You must be authenticated before using this API

Update Password¶

This endpoint updates a specific user’s password

HTTP Request¶

PUT http://example.com/api/v1/users/updatePassword

Request Parameters¶

Parameter	Type	Required	Default	Description
oldPassword	String	True		Current password
newPassword	String	True		New password

Response Parameters¶

Parameter	Type	Description
data	User	The modified User object

Attention

Remember — You must be authenticated before using this API

Get Current User’s Infomation¶

This endpoint retrieves a user’s infomation

HTTP Request¶

GET http://example.com/api/v1/users/me

Response Parameters¶

Parameter	Type	Description
data	User	The current User object

Attention

Remember — You must be authenticated before using this API

Update Current User’s Infomation¶

This endpoint updates a user’s infomation

HTTP Request¶

PATCH http://example.com/api/v1/users/me

Request Parameters¶

Parameter	Type	Required	Description
nickname	String	False	Nickname, max length = 100.
email	String	False	min length = 5, max length = 100
phoneNumber	String	False	min length = 5, max length = 20
avatar	String	False	Image URL of avatar, which can be external URL or hash value of an uploaded image file

Response Parameters¶

Parameter	Type	Description
data	User	The modified User object

Attention

Remember — You must be authenticated before using this API

Products¶

Product Entity Definition¶

Properties¶

Parameter	Type	Description
id	Integer	Product ID
seller	String	Username of seller
name	String	Name of this product
introduction	String	Introduction of this product. The content is defined by client’s implementation.
mainImageFiles	String[]	Hash values of product main images (max = 9). These files should be uploaded first.
createdAt	Date	Creation time
updatedAt	Date	Update time
price	Float	Price
ca	String	Certificate authority name
certId	String	Qualification certificate id
caFile	String	Certificate file hash value, this file should be uploaded first, and its type must be image or PDF
category	String	Categories of this product, separated by dot.
feature	String	Features. The content is defined by client’s implementation.
stat	ProductStat	Statistics Info for this product
valid	Boolean	Valid flag

Example JSON Representation¶

{
  "id": 1,
  "seller": {
    "username": "USERNAME_OF_SELLER",
    "nickname": "NICKNAME_OF_SELLER"
  },
  "name": "NAME_OF_THIS_PRODUCT",
  "introduction": "INTRODUCTION_OF_THIS_PRODUCT",
  "mainImageFiles": [
    "1dd4984b0d118569da8620fe67e7fd4bd2889bb316d5ee40ba914eb65f19107d",
    "d0673d4e73e191cc5ba3588f9eac52f7c15e4cba3fc3c229f47ea85d959f97b0"
  ],
  "createdAt": "2019-10-1 3:00 PM GMT+1:00",
  "updatedAt": "2019-10-1 3:00 PM GMT+1:00",
  "price": 10.00,
  "ca": "CNAS",
  "certId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "caFile": "28e51044f4a9cbae2bbd3d8a9d8c902ad1455d42208277ac4a913b003038a3dc",
  "stat"： {
    "salesLastMonth": 100,
    "currentStocks": 9999
  },
  "valid": true
}

Search Products by Parameters¶

This endpoint retrieves all products.

HTTP Request¶

GET http://example.com/api/v1/products

Request Parameters¶

Parameter	Type	Required	Default	Description
page	Integer	False	0	The page index from 0
size	Integer	False	20	Page size
valid	Boolean	False	True	Result products should be valid or invalid.
name	String	False		Name of this product. This field is matched in fuzzy mode.
introduction	String	False		Introduction of this product. This field is matched in fuzzy mode.
category	String	False		Categories of this product, separated by dot. This field is matched in fuzzy mode.
feature	String	False		Features. This field is matched in fuzzy mode.
global	String	False		Any product that contains this global search criterion in its name or introduction field will be matched

Note

The other fields will be ignored if global field is present. All other fields except global can be matched in combination.

Response Parameters¶

Parameter	Type	Description
data	Product[]	List of matching Product objects

Get a Specific Product¶

This endpoint retrieves a specific product.

HTTP Request¶

GET http://example.com/api/v1/products/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Product ID

Response Parameters¶

Parameter	Type	Description
data	Product	The matching Product object

Create a Product¶

This endpoint creates a new product.

HTTP Request¶

POST http://example.com/api/v1/products

Request Parameters¶

Parameter	Type	Required	Description
name	String	True	Name of this product
introduction	String	True	Introduction of this product
price	Float	True	Price of this product
ca	String	True	Certificate authority name
certId	String	True	Qualification certificate id
caFile	String	True	Hash of uploaded CA file
category	String	True	Categories of this product, separated by dot.
feature	String	True	Features. The content is defined by client’s implementation.
mainImageFiles	String[]	False	Main image URLs for this product, which can be the HASH value of uploaded images. Max length = 9

Response Parameters¶

Parameter	Type	Description
data	Product	The created Product object

Attention

Remember — You must be authenticated with SELLER role before using this API

Note

The order of mainImageFiles will be preserved.

Update a Specific Product¶

This endpoint updates infomation of a specific product.

HTTP Request¶

PATCH http://example.com/api/v1/products/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Product ID

Request Parameters¶

Parameter	Type	Required	Description
name	String	False	Name of this product
introduction	String	False	Introduction of this product
price	Float	False	Price of this product
ca	String	False	Certificate authority name
certId	String	False	Qualification certificate id
caFile	String	False	Hash of uploaded CA file
mainImageFiles	String[]	False	Main image URLs for this product, which can be the HASH value of uploaded images. Max length = 9

Attention

Remember — You must be authenticated with SELLER role before using this API

Note

The order of mainImageFiles will be updated to the same as you requested (if present).

Invalidate a Specific Product¶

This endpoint invalidates a specific product, so all stocks of this product will no longer be in the queue for sale.

It will NOT delete it from database.

HTTP Request¶

DELETE http://example.com/api/v1/products/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Product ID

Attention

Remember — You must be authenticated with SELLER role before using this API

Stocks¶

Stock Entity Definition¶

Properties¶

Parameter	Type	Description
id	Integer	Stock ID
product	Integer	Parent product ID
createdAt	Date	Creation time
updatedAt	Date	Update time
producedAt	Date	Production time
inboundedAt	Date	Inbound time
shelfLife	Integer	Shelf-Life of this stock
totalQuantity	Integer	Total quantity of this stock
currentQuantity	Integer	Current quantity of this stock
trackingId	String	Shipment tracking id
carrierName	String	Carrier name
valid	Boolean	Valid flag

Example JSON Representation¶

{
  "id": 1,
  "product": 2333,
  "createdAt": "2019-10-1 3:00 PM GMT+1:00",
  "updatedAt": "2019-10-1 3:00 PM GMT+1:00",
  "producedAt": "2019-10-1 3:00 PM GMT+1:00",
  "inboundedAt": "2019-10-1 3:00 PM GMT+1:00",
  "shelfLife": 365,
  "totalQuantity": 10000,
  "currentQuantity": 6999,
  "trackingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "carrierName": "SF-Express",
  "valid": true
}

Get Stocks by Parameters¶

This endpoint retrieves all stocks that satisfy given parameters

HTTP Request¶

GET http://example.com/api/v1/stocks

Request Parameters¶

Parameter	Type	Required	Default	Description
page	Integer	False	0	The page index from 0
size	Integer	False	20	Page size
productId	Integer	False		ID of the product it belongs to
shelfLife	Integer	False		Shelf-Life of the stock
trackingId	String	False		Tracking ID of this shipment
carrierName	String	False		Carrier Name of this shipment
valid	Boolean	False		The status of this stock

Response Parameters¶

Parameter	Type	Description
data	Stock[]	List of matching Stock objects

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API

Get a Specific Stock¶

This endpoint retrieves a specific stock with id

HTTP Request¶

GET http://example.com/api/v1/stocks/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Stock ID

Response Parameters¶

Parameter	Type	Description
data	Stock	The matching Stock object

Attention

Remember — You must be authenticated with SELLER role before using this API

Create a Stock¶

This endpoint creates a new product.

HTTP Request¶

POST http://example.com/api/v1/stocks

Request Parameters¶

Parameter	Type	Required	Description
productId	String	True	Parent product ID
producedAt	String	True	The producing date
shelfLife	Integer	True	Shelf-Life of this stock
totalQuantity	Integer	True	Total quantity of stock
trackingId	String	True	Tracking ID of this shipment
carrierName	String	True	Carrier Name of this shipment

Note

Example date string format: "2000-10-31T01:30:00.000-05:00"

Response Parameters¶

Parameter	Type	Description
data	Stock	The created Stock object

Attention

Remember — You must be authenticated with SELLER role before using this API

Invalidate a Specific Stock¶

This endpoint invalidates a specific stock, so all items from this stock will no longer be in the queue for sale.

It will NOT delete it from database.

HTTP Request¶

DELETE http://example.com/api/v1/stocks/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Stock ID

Attention

Remember — You must be authenticated with SELLER role before using this API

Orders¶

Order Entity Definition¶

Properties¶

Parameter	Type	Description
id	String	Order ID
quantity	Integer	Quantity of this order
createdAt	Date	Creation time
updatedAt	Date	Update time
customer	String	Customer username who creates this order
address	AddressBean	Associated Address object of this order
product	Integer	Parent product id
stocks	Integer[]	The related stocks of this order
trackingId	String	Shipment tracking id
carrierName	String	Carrier name
totalAmount	Float	Total amount
remark	String	Addtional infomation of this order
shippingTime	Date	The time of shipping
deliveryConfirmed	Boolean	Whether the delivery is confirmed by customer
paid	Boolean	Whether the order is paid
valid	Boolean	Valid flag

Example JSON Representation¶

{
  "id": "c3beaaf0-ff02-4adf-b37c-ee41dbc20319",
  "quantity": 2,
  "createdAt": "2019-10-1 3:00 PM GMT+1:00",
  "updatedAt": "2019-10-1 3:00 PM GMT+1:00",
  "customer": "FOO",
  "address": {
    "province": "Beijing",
    "city": "Beijing",
    "district": "Haidian",
    "address": "Jianguo Avenue",
    "zip": "100000"
  },
  "product": 1,
  "stocks": [11, 12, 13, 14, 15],
  "trackingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "carrierName": "SF-Express",
  "totalAmount": 500.00,
  "remark": null,
  "shippingTime": "2019-10-1 3:00 PM GMT+1:00",
  "deliveryConfirmed": false,
  "paid": false,
  "valid": true
}

Get Orders by Parameters¶

This endpoint retrieves all orders that satisfy given parameters

HTTP Request¶

GET http://example.com/api/v1/orders

Request Parameters¶

Parameter	Type	Required	Default	Description
page	Integer	False	0	The page index from 0
size	Integer	False	20	Page size
customerId	String	False		Username of the customer
trackingId	String	False		Tracking ID of a shipped order
stockId	Integer	False		The stock ID it belongs to
valid	Boolean	False		Valid flag
deliveryConfirmed	Boolean	False		Whether the delivery is confirmed by customer
paid	Boolean	False		Whether the order is paid

Response Parameters¶

Parameter	Type	Description
data	Order[]	List of matching Order objects

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API

Get a Specific Order¶

This endpoint retrieves a specific order

HTTP Request¶

GET http://example.com/api/v1/orders/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Order ID

Response Parameters¶

Parameter	Type	Description
data	Order	The matching Order object

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API

Create an Order¶

This endpoint creates a new order.

HTTP Request¶

POST http://example.com/api/v1/orders

Request Parameters¶

Parameter	Type	Required	Description
productId	Integer	True	ID of the product it belongs to
quantity	Integer	True	Quantity of this order
customerId	String	True	Customer username who creates this order
addressId	Integer	True	Destination address ID from address book
remark	String	False	Remark

Response Parameters¶

Parameter	Type	Description
data	Order	The created Order object

Attention

Remember — You must be authenticated with CUSTOMER role before using this API

Cancel a Specific Order¶

This endpoint cancels a specific order.

HTTP Request¶

DELETE http://example.com/api/v1/orders/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Order ID

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API

You can only cancel an order which has not been shipped.

Delivery Confirmation¶

This endpoint confirms delivery of an order.

HTTP Request¶

PATCH http://example.com/api/v1/orders/<ID>/DELIVERY_CONFIRM

Path Parameter¶

Parameter	Required	Description
ID	True	Order ID

Response Parameters¶

Parameter	Type	Description
data	Order	The modified Order object

Attention

Remember — You must be authenticated with CUSTOMER role before using this API

Update an Order¶

This endpoint updates shipment details of an order.

HTTP Request¶

PATCH http://example.com/api/v1/orders/<ID>/SHIP

Path Parameter¶

Parameter	Required	Description
ID	True	Order ID

Request Parameters¶

Parameter	Type	Required	Description
trackingId	String	True	Tracking ID from shipment carrier
carrierName	String	True	Shipment carrier name
shippingTime	String	True	Time of shipping

Note

Example date string format: "2000-10-31T01:30:00.000-05:00"

Response Parameters¶

Parameter	Type	Description
data	Order	The modified Order object

Attention

Remember — You must be authenticated with SELLER role before using this API

Payments¶

Payment Entity Definition¶

Properties¶

Parameter	Type	Description
id	Integer	Payment ID
order	String	Parent Order ID
orderString	String	Alipay redirect URL
createdAt	Date	Creation time
updatedAt	Date	Update time
payer	String	Username of payer
subject	String	Subject of this payment
description	String	Description
totalAmount	Float	Total amount
status	String	One of [‘PENDING’, ‘CONFIRMED’, ‘TIMEOUT’, ‘INVALID’]
vendorTradeId	String	Unique trade id from vendor.
confirmedAt	Date	Payment confirmation time
confirmed	Boolean	Whether the payment is confirmed by system
valid	Boolean	Valid flag

Example JSON Representation¶

{
  "id" : 1,
  "order" : "c3beaaf0-ff02-4adf-b37c-ee41dbc20319",
  "orderString" : "https://openapi.alipaydev.com/gateway.do?XXX=XXX",
  "createdAt" : "2019-04-19T15:31:20.807+0000",
  "updatedAt" : "2019-04-19T15:31:20.807+0000",
  "payer" : "test_user_customer_username_0",
  "subject" : "Test Subject",
  "description" : "Test Description",
  "totalAmount" : 1000.123,
  "status" : "PENDING",
  "vendorTradeId" : null,
  "confirmedAt" : null,
  "confirmed" : false,
  "valid" : false
}

Get Related Payments for an Order¶

This endpoint retrieves all related payments for an order.

HTTP Request¶

GET http://example.com/api/v1/payments

Request Parameters¶

Parameter	Type	Required	Default	Description
orderId	String	True		Parent Order ID

Response Parameters¶

Parameter	Type	Description
data	Payment[]	List of matching Payment objects

Attention

Remember — You must be authenticated before using this API

The requested order must belongs to you.

Get a Specific Payment¶

This endpoint retrieves a specific payment with id.

HTTP Request¶

GET http://example.com/api/v1/payments/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Payment ID

Response Parameters¶

Parameter	Type	Description
data	Payment	The matching Payment object

Attention

Remember — You must be authenticated before using this API

The requested payment must belongs to you.

Create a Payment¶

This endpoint creates a new payment.

HTTP Request¶

POST http://example.com/api/v1/payments

Request Parameters¶

Parameter	Type	Required	Description
orderId	String	True	Parent Order ID
subject	String	True	Subject of this payment
description	String	False	Description

Response Parameters¶

Parameter	Type	Description
data	Payment	The created Payment object

Attention

Remember — You must be authenticated with CUSTOMER role before using this API

orderString will expire after 15 minutes.

Retry Payment Action¶

This endpoint re-obtains orderString for a payment.

HTTP Request¶

GET http://example.com/api/v1/payments/retry/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Payment ID

Response Parameters¶

Parameter	Type	Description
data	Payment	The matching Payment object with new orderString

Verify Payment¶

This endpoint performs payment verifification triggered by client.

Usually, the system will verify a payment in three ways:

Receive asynchronous verification message posted by third-party payment vendor.
Query payment status positively as a scheduled task.
Perform verification asked by client.

HTTP Request¶

GET http://example.com/api/v1/payments/verify/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Payment ID

Response Parameters¶

Parameter	Type	Description
data	Boolean	The verification status

Refunds¶

Refund Entity Definition¶

Properties¶

Parameter	Type	Description
id	Integer	Refund ID
order	Integer	Order ID
createdAt	Date	Creation time
updatedAt	Date	Update time
requester	String	Username of requester
requestReason	String	Reason of requester
responseReason	String	Reason of responder. e.g. The reason of rejection.
confirmedAt	Date	Refund confirm time
issuedAt	Date	Refund issue time
amount	Float	Amount
status	String	Status, one of [‘PROCESSING’, ‘DENIED’, ‘ISSUED’, ‘CANCELLED’, ‘REQUESTED’, ‘WAITING’]
trackingId	String	Shipment tracking id
carrierName	String	Carrier name
refundOnly	Boolean	If false, then customer should provide shipment infomation later
valid	Boolean	Valid flag

Example JSON Representation¶

{
  "id": 1,
  "order": 5,
  "createdAt": "2019-10-1 3:00 PM GMT+1:00",
  "updatedAt": "2019-10-1 3:00 PM GMT+1:00",
  "requester": "USERNAME_OF_REFUND_ISSUER",
  "requestReason": "I hate this product",
  "responseReason": null,
  "confirmedAt": null,
  "issuedAt": null,
  "amount": 500.0,
  "status": "REQUESTED",
  "trackingId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "carrierName": "SF-Express",
  "refundOnly": false,
  "valid": true
}

Get Refunds Infomation¶

This endpoint gets infomation of refunds.

HTTP Request¶

GET http://example.com/api/v2/refunds

Request Parameters¶

Parameter	Type	Required	Default	Description
page	Integer	False	0	The page index from 0
size	Integer	False	20	Page size
orderId	String	False		Order ID
status	String	False		Status, one of [‘PROCESSING’, ‘DENIED’, ‘ISSUED’, ‘CANCELLED’, ‘REQUESTED’, ‘WAITING’]
valid	Boolean	False		Valid flag

Response Parameters¶

Parameter	Type	Description
data	Refund[]	List of matching Refund objects

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API The requested orderId (if provided) must belong to you.

Get Infomation of a Specific Refund¶

This endpoint get infomation of a specific refund.

HTTP Request¶

GET http://example.com/api/v2/refunds/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Refund ID

Response Parameters¶

Parameter	Type	Description
data	Refund	The matching Refund object

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API

Create a Refund¶

This endpoint creates a new refund.

HTTP Request¶

POST http://example.com/api/v2/refunds

Request Parameters¶

Parameter	Type	Required	Description
orderId	Integer	True	ID of the order it belongs to
reason	String	True	Reason of this refund
amount	Float	True	Refund amount
refundOnly	Boolean	True	If false, then customer should provide tracking infomation later

Response Parameters¶

Parameter	Type	Description
data	Refund	The created Refund object

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API

Provide shipment infomation for a refund¶

This endpoint provides shipment infomation for a refund.

HTTP Request¶

PATCH http://example.com/api/v2/refunds/<id>

Path Parameter¶

Parameter	Required	Description
ID	True	Refund ID

Request Parameters¶

Parameter	Type	Required	Description
action	String	True	Should be `SHIP_INIT`
trackingId	String	True	Shipment tracking id
carrierName	String	True	Carrier name

Response Parameters¶

Parameter	Type	Description
data	Refund	The modified Refund object

Attention

Remember — You must be authenticated with CUSTOMER role before using this API

You can only provide shipment infomation for a refund whose refundOnly is false

Cancel a Specific Refund¶

This endpoint cancels a specific refund.

HTTP Request¶

DELETE http://example.com/api/v2/refunds/<ID>

Path Parameter¶

Parameter	Description
ID	Refund ID

Attention

Remember — You must be authenticated with SELLER or CUSTOMER role before using this API

You can only cancel a refund which is in [ ‘PENDING’, ‘WAITING’, ‘REQUESTED’ ] status.

Files¶

File MetaData Definition¶

Properties¶

Parameter	Type	Description
id	Integer	File ID
createdAt	Date	Creation time
hash	String	SHA-256 hash value of the file content
referrenceCount	Integer	Referrence Count of this file object
mimetype	String	MIME type of the file

Allowed File Types¶

Extension (Ignore case)	MIME Type	Size Limit
.jpg	image/jpeg	10M
.jpeg	image/jpeg
.gif	image/gif
.png	image/png
.svg	image/svg+xml
.wav	audio/wav	5M
.mp3	audio/mpeg	5M
.mp4	video/mp4	100M
.avi	video/x-msvideo
.mpeg	video/mpeg
.pdf	application/pdf	20M

Attention

If a file has no referrence (referrenceCount == 0) 15 minutes after creation, it will be deleted from server.

Example JSON Representation¶

{
  "id": 1,
  "createdAt": "2019-10-1 3:00 PM GMT+1:00",
  "hash": "1dd4984b0d118569da8620fe67e7fd4bd2889bb316d5ee40ba914eb65f19107d",
  "referrenceCount": 0,
  "mimetype": "image/jpeg"
}

Upload a File¶

This endpoint uploads a new file.

HTTP Request¶

POST http://example.com/api/v1/files

Request Parameters¶

Parameter	Type	Required	Default	Description
file	File	True		The file object

Response Parameters¶

Parameter	Type	Description
data	FileMeta	The associated File MetaData object of the created file

Attention

Remember — You must be authenticated before using this API

Get a Specific File¶

This endpoint provides a direct access to the requested file.

HTTP Request¶

GET http://example.com/api/v1/files/<HASH>

Path Parameter¶

Parameter	Required	Description
HASH	True	The SHA-256 hash value of a file object in server, which should be the same as the hash value returned from File-Upload API

Delete a Specific File¶

This endpoint decreases a file’s referrenceCount.

The file will be deleted from server once its referrenceCount reaches zero.

HTTP Request¶

DELETE http://example.com/api/v1/files/<HASH>

Path Parameter¶

Parameter	Required	Description
HASH	True	The SHA-256 hash value of a file object in server, which should be the same as the hash value returned from File-Upload API

Addresses¶

Address Entity Definition¶

Properties¶

Parameter	Type	Description
id	Integer	Address ID
owner	String	Username of the owner
province	String	Province
city	String	City
district	String	District
address	String	Detailed address
zip	String	ZIP code

Example JSON Representation¶

{
  "id": 1,
  "owner": "FOO",
  "province": "Beijing",
  "city": "Beijing",
  "district": "Haidian",
  "address": "No.XX XXX Road",
  "zip": "100000",
}

Get a Specific Address¶

This endpoint retrieves a specific address

HTTP Request¶

GET http://example.com/api/v1/addresses/<ID>

Path Parameter¶

Parameter	Required	Description
ID	True	Address ID

Response Parameters¶

Parameter	Type	Description
data	Address	The matching Address object

Attention

Remember — You must be authenticated before using this API.

The requested address must belong to you.

Get Current User’s Addresses¶

This endpoint retrieves all addresses of current user.

HTTP Request¶

GET http://example.com/api/v1/addresses

Response Parameters¶

Parameter	Type	Description
data	Address[]	List of matching Address objects

Attention

Remember — You must be authenticated before using this API.

Create an Address¶

This endpoint creates a new address.

HTTP Request¶

POST http://example.com/api/v1/addresses

Request Parameters¶

Parameter	Type	Required	Default	Description
province	String	True		Province
city	String	True		City
district	String	True		District
address	String	True		Detailed address
zip	String	False	000000	Zip code

Attention

Remember — You must be authenticated before using this API

Generals¶

Standard Response Structure¶

All responses have same general structure

Response Parameters¶

Parameter	Type	Required	Default	Description
responseId	String	True		The UUID of this response
timestamp	Date	True		Generation time of this response
success	Boolean	True		The status flag which indicates whether your API call is success
data	Any	True	null	The message body of this response, which can be any object that supported by JSON
error	Error	True	null	Associated Error object (if applicable)

The response JSON structured like this

{
  "responseId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "timestamp":"2019-04-21T12:00:56.375+0000",
  "sucess": true,
  "data": null,
  "error": null
}

{
  "responseId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "timestamp":"2019-04-21T12:00:56.375+0000",
  "sucess": false,
  "data": null,
  "error": {
    "type": "API.SECURITY.ACCESS_DENIED",
    "message": "Access Denied"
  }
}

Standard Error Definition¶

Properties¶

Parameter	Type	Required	Default	Description
type	String	True		Error Type
message	String	True		Explanation of this error

Example JSON Representation¶

{
  "type": "API.SECURITY.ACCESS_DENIED",
  "message": "Access Denied"
}

HTTP Status Codes¶

Success¶

Success Code	Meaning
200	OK – Standard response for successful HTTP requests
201	Created – The request has been fulfilled, resulting in the creation of a new resource.
202	Accepted — The request has been accepted for processing, but the processing has not been completed.

Errors¶

The LLZW API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request is invalid.
401	Unauthorized – Your are unauthorized.
403	Forbidden — You do not have privilege to perform this request.
404	Not Found – The specified kitten could not be found.
405	Method Not Allowed – You tried to access a kitten with an invalid method.
406	Not Acceptable – You requested a format that isn’t json.
410	Gone – The object requested has been removed from our servers.
429	Too Many Requests – You’re requesting too many kittens! Slow down!
500	Internal Server Error – We had a problem with our server. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.