| Name: | PartnerServiceBasic |
| Purpose: | Site for partners. |
| Version: | 1.1 |
| Protocol: | REST, OData v2 |
| Address: | https://partnerzyapi.ceneo.pl/PartnerServiceBasic.svc |
| Metadata: | https://partnerzyapi.ceneo.pl/PartnerServiceBasic.svc/$metadata |
| Authorization: | OAuth 2.0 protocol, 'client_credentials’ mode, Bearer token |
| REST | Representational state transfer (REST) - a style of software architecture for services providing data in the form of resources. Individual resources are identified using a uniform resource identifier (URI).
http://en.wikipedia.org/wiki/Representational_state_transfer |
| URI | Uniform Resource Locator - a uniform resource identifier on the Web. http://en.wikipedia.org/wiki/Uniform_Resource_Identifier, http://www.ietf.org/rfc/rfc3986.txt |
| OData | Open Data Protocol - a REST protocol dedicated for loading and updating data. It uses the ATOM standard and AtomPub protocol. http://www.odata.org/ |
| OAuth 2.0 | Authorization protocol in HTTP services http://tools.ietf.org/html/draft-ietf-oauth-v2-22 |
| Atom | Standard of data definition based on XML document. http://tools.ietf.org/html/rfc4287 |
| AtomPub | Atom Publishing Protocol – information publishing standard in services, which is to replace RSS channels in the future. http://tools.ietf.org/html/rfc5023 |
| JSON | JavaScript Object Notation – a text-based notation of data entry, based on the JavaScript language. http://en.wikipedia.org/wiki/JSON |
| HTTP status codes | HTTP queries always return a status code informing about operation result. Below you may find a link to the list of statuses: http://en.wikipedia.org/wiki/List_of_HTTP_status_codes |
The site is a REST-based service providing resources using the OData protocol,
allowing for performance of selected operations using the GET protocol.
Data and access security is ensured by encrypted connection and use of the
OAuth protocol for authorisation. The site automatically provides data on resources,
data types and operations it contains. Errors are always return in an http reply header.
The site can be accessed only by users of the Affiliate Program on Ceneo.pl.
Access to authorisation is secured with an SSL certificate and should be made using https. Access to data may be provided using non-encrypted http.
Access to the site, its resources and operations needs to be authorised first using a special token (a string of characters) which is generated once for a specified period of time after which it expires. The token is of a single use, which means that after its expiry, it will be impossible to use it for authorisation.
Note! An authorisation token cannot be downloaded using http, because it may compromise the API key.
Access to each resource and operation is based on the OAuth 2.0 protocol and the client_credentials authorisation type. To connect to the site, the customer needs to download an access token first by providing an API key. The token is generated in the Basic authorisation mode using a special service, i.e. AuthorizationService.svc, and the GetToken method accepting the grant type as a parameter and requiring the API key to be sent in the GET https query header.
Data to be sent in the header:
Authorization: Basic api_key
Sample call:
URI
/AuthorizationService.svc/GetToken?grantType='client_credentials'
Header
Authorization: Basic F7869662-F334-427C-94B9-2D876BFCD589
In reply a customer receives a token in the header together with information on its type and validity time in seconds after which it will expire. The token type has always the “bearer” value.
If any parameter is incorrect, the HTTP 400 BadRequest error will be returned together with a detailed message in accordance with the OAuth 2.0 specification.
If a user has no rights to access the resources, the HTTP 401 Unauthorized error will be returned.
Data to be read in the header:
access_token: token
expires_in: time_in_seconds
token_type: token_type
Sample response:
access_token: 8aYW5uonggPM0mKtARb0TyT_rOtCxJIChmmWWfmD-_c.
expires_in: 900
token_type: bearer
The token should be added to the header of each query for resources and performance of operation (except for loading a new token) in the following way:
Authorization: Bearer token
Sample header:
Authorization: Bearer 8aYW5uonggPM0mKtARb0TyT_rOtCxJIChmmWWfmD-_c.
It can also be added as URI parameter:
/Categories?access_token=8aYW5uonggPM0mKtARb0TyT_rOtCxJIChmmWWfmD-_c.
If the token has expired or the query is without any token, the HTTP 401 Unauthorized error is to be returned.
HTTP error details are returned in the http header in three parameters (also compliant with OAuth 2.0):
error: shortened error_code_–_string_of_characters
error_description: short_description_–_string_of_characters,_optionally
error_uri: address_to_webpage_with_detailed_description_–_string_of_characters,_optionally
The site provides metadata describing all available resources and operations as well as data types.
Metadata is available at
/Service_name.svc/$metadata
To access it, no encrypted connection or authorization is required (it is possible to query using http).
URI is defined using OData protocol.
The resource access template is as follows:
/Site_name.svc/Resource_name?$optional_parameters
The operation call template is as follows:
/Site_name.svc/Operation_name?optional_parameters
Collections may be transmitted for operations only in Query String parameters in GET operations. A collection needs to be serialised to the JSON format.
Query String parameters need to be encoded as UTF8. For example, in JavaScript this can be done using the encodeURIComponent function. Encoding is defined in the URI standard.
Data is returned by default as ATOM XML, but it is possible to request JSON format by adding the $format=json parameter.
Sample:
/Site_name.svc/Resource_name_or_Operation_name?optional_parameters&$format=json
Results of queries for resources and operations (except for loading a token) are kept for 15 minutes, which means that during that time the same query will return the same data even though it could change. The data storage time may change.
Quantitative limits may be imposed for queries for resources and operations (hourly, daily, etc.). Then, after the limit is exceeded, the HTTP 403 Forbidden error will be returned together with the error code and description informing that the number of calls has been exceeded.
| Name | Type | Description |
|---|---|---|
| Id | Int32 | Category ID |
| Name | String | Name |
| Name | Type | Description |
|---|---|---|
| Id | Int32 | Product ID |
| Name | String | Name |
| CategoryId | Int32 | Category ID |
| LowestPrice | Decimal | Lowest price |
| Shops | Int32 | Number of shops where product can be bought |
Empty
