Overview

General Principles

HTTP Request Methods

The CASE service should adhere as closely as possible to standard HTTP and REST principles.

Request Method	Usage
GET	Retrieve a resource
POST	Create a new resource or query an existing one
PUT	Update an existing resource
DELETE	Delete an existing resource

Pagination

CASE service responses that require pagination will conform to the following message format:

Parameter	Type	Optional	Description
paging	Object	true	Pagination object
paging.pageNum	Integer	true	Page number
paging.pageSize	Integer	true	Page size
paging.total	Long	true	Total number of items

HTTP Status Codes

The CASE service should adhere as closely as possible to standard HTTP and REST principles.

Status Code	Usage
200 OK	Standard response for successful HTTP requests. The actual response will depend on the request method. For GET requests, the response will contain an entity corresponding to the requested resource. For POST requests, the response will contain a description of the entity or the result of the action.
201 Created	The request has been fulfilled, resulting in the creation of a new resource.
204 No Content	The server successfully processed the request but is not returning any content.
400 Bad Request	The server cannot or will not process the request due to client error (e.g., incorrect syntax, invalid request message framing, deceptive request routing).
401 Unauthorized	Unauthorized.
404 Not Found	The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.
500 Internal Server Error	A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

Invocation Address

Format

https://km.udesk.cn/api/v1/{relative address}?{URL params}&email={administrator email}&timestamp={timestamp}&sign={signature}

Where parts in curly brackets mean:

Variable	Description
relative address: Interface relative address	The relative URL of the API
URL params: URL parameters	Parameters required for requesting the interface
administrator email: Administrator email	The email address of the super administrator
timestamp: Timestamp	The timestamp when the request is initiated, in seconds since '1970-01-01 00:00:00'. Unless otherwise specified, the default expiration time is five minutes.
signature: Signature	Authentication signature. Unless otherwise specified, this parameter is required for each API request. Refer to the detailed generation algorithm in the "Authentication Method" section.

Parameters Three types of parameters:

Type	Description
Path parameters	Part of the request URL Path, such as :id in /leads/:id
Query parameters	Parameters when requesting the interface, such as page=10 in /leads?page=10
Request fields	Request body (Request Body)

Return UTF-8 encoded JSON string

Authentication Method

Formula

sign=SHA1(email&api_token&timestamp)

Where:

• email: Administrator email address
• api_token: Authentication private key, available in the km system at Top right corner gear (Admin) - System settings - Key
• timestamp: Timestamp, in seconds since '1970-01-01 00:00:00'

Example

https://km.udesk.cn/api/v1/leads

Data required for authentication:

Name	Value
email	email@udesk.cn
api_token	221b368d7f5f597867f525971f28ff75
timestamp	1496631984

Calculate the signature:

sha1("email@udesk.cn&221b368d7f5f597867f525971f28ff75&1496631984") -> a32be53bb42314850715f8b9ab92542f5ed54c5e

Request URL:

https://km.udesk.cn/api/v1/leads?email=email@udesk.cn&timestamp=1496631984&sign=a32be53bb42314850715f8b9ab92542f5ed54c5e