kaletat/XQuery-Allegro-API
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

XQuery Allegro API

Browse Source
This commit is contained in:
kaletat
2019-08-21 19:30:57 +02:00
commit 699c520da5
6 changed files with 567 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
XQuery Allegro API/API/api.xqm Normal file
View File

@@ -0,0 +1,227 @@
xquery version "3.1";
(:
: Module Name: XQuery Allegro API Application Library Module
:
: Module Version: 1.0
:
: Date: June 26, 2019
:
: Copyright: release11.com
:
: Properietary
: Extensions: none
:
: XQuery
: Specification: April 2019
:
: Module Overview: This module contains XQuery Allegro API functions.
:)
(:~
: This module provides basic Allegro RESTApi functions that allow
: to search offers, categories and categories id.
:
: @author Tomasz Kaleta
: @since June 26, 2019
: @version 1.0
:)
module namespace allegro="http://release11.com/xquery-allegro-api/api";
import module namespace hc="http://expath.org/ns/http-client"; (: include in docs why its expath:)
(:~
: FOR SPECIFIC DESCRIPTION OF EACH PARAMETER GO TO THIS LINK: https://developer.allegro.pl/documentation/#operation/getListing
:)
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter identifies category in which offers are searched.
:)
declare variable $allegro:categoryId as xs:string := "category.id";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter identifies phrase to search for.
:)
declare variable $allegro:phrase as xs:string := "phrase";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter limits search results to offers from one seller.
:)
declare variable $allegro:sellerId as xs:string := "seller.id";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter indicates fields to include in search.
:)
declare variable $allegro:searchMode as xs:string := "searchMode";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter sets index of first returned offer.
:)
declare variable $allegro:offset as xs:string := "offset";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter limits returned offers.
:)
declare variable $allegro:limit as xs:string := "limit";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter identifies category in which offers are searched.
:)
declare variable $allegro:sort as xs:string := "sort";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter determinates which entities will be returned in results.
:)
declare variable $allegro:include as xs:string := "include";
(:~
: This variable contains parameter name that is available in Allegro RESTApi to search offers.
: This parameter determinates what happens when no results found.
:)
declare variable $allegro:fallback as xs:string := "fallback";
(:~
: This variable contains all parameters names that are available in Allegro RESTApi to search offers.
: Variable is used to validate maps with parameters passed by user.
:)
declare variable $allegro:availableParams as xs:string* :=
("category.id",
"phrase",
"sort",
"seller.id",
"searchMode",
"offset",
"limit",
"include",
"fallback"
);
(:~
: This function gets offers from allegro based on user's criterias.
:
: @param $authorizationHeader token type and encoded access token to authorize user.
: @param $parametersMap search parameters.
: @return result of the search.
:)
declare function allegro:get-offers($authorizationHeader as xs:string,
$offersUrl as xs:string,
$parametersMap as map(*))
as item()+
{
if (allegro:validate-parameters-map($parametersMap) = 1) then
let $parameters := string-join(map:for-each($parametersMap,
function($key, $value) {string-join(($key, $value), "=")}),
"&")
let $url := concat($offersUrl, $parameters)
return
http:send-request(
<hc:request method="get" href ="{$url}">
<hc:header name="Authorization" value="{$authorizationHeader}"/>,
<hc:header name="Accept" value="application/vnd.allegro.public.v1+json"/>
</hc:request>
)
else ()
};
(:~
: This function gets categories list available in Allegro.
:
: @param $authorizationHeader token type and encoded access token to authorize user.
: @return available categories.
:)
declare function allegro:get-categories($authorizationHeader as xs:string,
$categoriesUrl as xs:string)
as item()+
{
allegro:get-category-private($authorizationHeader, $categoriesUrl, ())
};
(:~
: This function gets category params by given id.
:
: @param $authorizationHeader token type and encoded access token to authorize user.
: @param $categoryId category id.
: @return category with given id.
:)
declare function allegro:get-category-by-id($authorizationHeader as xs:string,
$categoriesUrl as xs:string,
$categoryId as xs:integer)
as item()+
{
allegro:get-category-private($authorizationHeader, $categoriesUrl, $categoryId)
};
(:~
: This function gets category parameters by given id.
:
: @param $authorizationHeader token type and encoded access token to authorize user.
: @param $categoryId category id
: @return list of parameters that are supported by the given category
:)
declare function allegro:get-category-params($authorizationHeader as xs:string,
$categoriesUrl as xs:string,
$categoryId as xs:integer)
as item()+
{
http:send-request(
<hc:request method="get" href="https://api.allegro.pl/sale/categories/{$categoryId}/parameters">
<hc:header name="Authorization" value="{$authorizationHeader}"/>,
<hc:header name="Accept" value="application/vnd.allegro.public.v1+json"/>
</hc:request>
)
};
(:~
: This is private function that builds URL to use category functions depends on what type of search is called.
:
: @param $authorizationHeader token type and encoded access token to authorize user.
: @param $categoryId category id
: @return list of categories or category with given id
:)
declare %private function allegro:get-category-private($authorizationHeader as xs:string,
$categoriesUrl as xs:string,
$categoryId as xs:integer*)
as item()+
{
let $url :=
if ($categoryId) then
concat($categoriesUrl, $categoryId)
else
$categoriesUrl
return
http:send-request(
<hc:request method="get" href="{$url}">
<hc:header name="Authorization" value="{$authorizationHeader}"/>,
<hc:header name="Accept" value="application/vnd.allegro.public.v1+json"/>
</hc:request>
)
};
(:~
: This function checks if map with parameters passed by user is valid.
: If map contains parameters that are not supported by Allegro RESTApi error is thrown.
:
: @param $parametersMap map containing search parameters.
: @return 1 if map is valid or 0 if it is not.
:)
declare %private function allegro:validate-parameters-map($parametersMap as map(*))
as xs:integer
{
let $user-keys := map:keys($parametersMap)
return
if (distinct-values($user-keys[not(.=$allegro:availableParams)])) then
error()
else
1
};

69
XQuery Allegro API/API/authorization.xqm Normal file
View File

@@ -0,0 +1,69 @@
xquery version "3.1";
(:
: Module Name: XQuery Allegro API Authorization Library Module
:
: Module Version: 1.0
:
: Date: June 26, 2019
:
: Copyright: release11.com
:
: Properietary
: Extensions: none
:
: XQuery
: Specification: April 2019
:
: Module Overview: This module authorizes an user.
:)
(:~
: This module authorizes an user and allows acces to Allegro RESTApi with access token.
:
: @author Tomasz Kaleta
: @since June 26, 2019
: @version 1.0
:)
module namespace auth="http://release11.com/xquery-allegro-api/authorization";
import module namespace hc="http://expath.org/ns/http-client";
(:~
: This function gets access token from Allegro authorization service.
: Token is necessary to authenticate an apllication.
:
: @param authorizationUrl Allegro OAuth 2.0 authorization endpoint
: @param base64credentials base64 encoded client id and client secret joined by ':'.
: @return access token.
:)
declare function auth:get-access-token($authorizationUrl as xs:string,
$base64credentials as xs:string)
as xs:string
{
let $accessTokenResponse :=
hc:send-request(
<hc:request method="post" href="{$authorizationUrl}" >
<hc:header name="Authorization" value="Basic {$base64credentials}"/>
</hc:request>
)
return
$accessTokenResponse//access__token
};
(:~
: This function concats token type and access token.
:
: @param $accessToken accesToken granted by authorization service.
@param $tokenType type of the token required by authorization service.
: @return authorization header required to be sent with every request.
:)
declare function auth:get-authorization-header($accessToken as xs:string,
$tokenType as xs:string)
as xs:string
{
string-join(($tokenType, $accessToken), ' ')
};

12
XQuery Allegro API/API/main.xq Normal file
View File

@@ -0,0 +1,12 @@
xquery version "3.1";
import module namespace auth="http://release11.com/xquery-allegro-api/authorization" at "authorization.xqm";
import module namespace allegro="http://release11.com/xquery-allegro-api/api" at "api.xqm";
let $accessToken := auth:get-access-token("https://allegro.pl/auth/oauth/token?grant_type=client_credentials","NGI3OWMyM2RhOTMxNGE2Y2E0MzhmYTg0YjhjYzA3MDg6UjB5SERBR292TVRDUFQ3aDMxbjltUHNxNWtNT1o1cktZS3k2aXN3dUFMNVppbzBqem9EYkFidU5WYjJsdkp3TQ==")
let $authorizationHeader := auth:get-authorization-header($accessToken, "Bearer")
let $categories := allegro:get-categories($authorizationHeader, "https://api.allegro.pl/sale/categories")
return $categories

163
XQuery Allegro API/API/test.xqm Normal file
View File

@@ -0,0 +1,163 @@
xquery version "3.1";
(:
: Module Name: XQuery Allegro API Test Library Module
:
: Module Version: 1.0
:
: Date: June 26, 2019
:
: Copyright: release11.com
:
: Properietary
: Extensions: none
:
: XQuery
: Specification: March 2019
:
: Module Overview: This contains tests for Allegro RESTApi.
:)
(:~
: This module provides unit tests.
:
: @author Tomasz Kaleta
: @since June 26, 2019
: @version 1.0
:)
module namespace test = "http://release11.com/allegro/test";
import module namespace allegro = "http://release11.com/xquery-allegro-api/api" at "api.xqm";
import module namespace auth = "http://release11.com/xquery-allegro-api/authorization" at "authorization.xqm";
(:~
: This variable contains valid parameters map for get-offers() function from Application Library Module.
:)
declare variable $test:validMap := map {'category.id' : '5','phrase' : 'iphone', 'sort' : '+price', 'seller.id' : '3252', 'searchMode' : 'REGULAR','offset' : '100', 'limit' : '20', 'include' : 'free', 'fallback' : 'true()' };
(:~
: This variable contains invalid parameters map for get-offers() function from Application Library Module.
:)
declare variable $test:invalidMap := map {'category.id' : '5','phrase' : 'iphone', 'notValidParam' : '+price'};
(:~
: This variable contains client id and client secret encoded in base64.
:)
declare variable $test:base64credentials as xs:string := "NGI3OWMyM2RhOTMxNGE2Y2E0MzhmYTg0YjhjYzA3MDg6UjB5SERBR292TVRDUFQ3aDMxbjltUHNxNWtNT1o1cktZS3k2aXN3dUFMNVppbzBqem9EYkFidU5WYjJsdkp3TQ==";
(:~
: This variable contains client id and client secret encoded in base64.
:)
declare variable $test:tokenType as xs:string := "Bearer";
(:~
: This variable contains access token granted by authorization server.
:)
declare variable $test:accessToken as xs:string := auth:get-access-token("https://allegro.pl/auth/oauth/token?grant_type=client_credentials", $test:base64credentials);
(:~
: This variable contains authorization header.
:)
(:~
: This variable contains authorization header.
:)
declare variable $test:authorizationUrl as xs:string := "https://allegro.pl/auth/oauth/token?grant_type=client_credentials";
(:~
: This variable contains base of url to search offers.
:)
declare variable $test:offersUrl as xs:string := "https://api.allegro.pl/offers/listing?";
(:~
: This variable contains base of url to search categories.
:)
declare variable $test:categoriesUrl as xs:string := "https://api.allegro.pl/sale/categories/";
(:~
: Test checks if response for token request contains access token .
declare %unit:test function test:should-contain-access-token()
{
unit:assert(not(empty(auth:get-access-token("https://allegro.pl/auth/oauth/token?grant_type=client_credentials", $test:base64credentials))))
};
:)
declare variable $test:authorizationHeader := auth:get-authorization-header($test:accessToken, $test:tokenType);
(:~ Test checks if response for token request contains access token :)
declare %unit:test function test:should-contain-access-token(
)
{
unit:assert(string-length(auth:get-access-token($test:authorizationUrl, $test:base64credentials)) > 0 )
};
(:~
: Test should return error as map contains invalid input parameter.
:)
declare %unit:test("expected", "err:FOER0000") function test:should-return-error-invalid-param()
{
allegro:get-offers($test:authorizationHeader, $test:offersUrl, $test:invalidMap)
};
(:~
: Test should pass and request should be send as map contains only valid input parameters.
:)
declare %unit:test function test:should-pass-get-offers()
{
unit:assert(allegro:get-offers($test:authorizationHeader, $test:offersUrl, $test:validMap))
};
(:~
: Test should pass and response status should be 200.
:)
declare %unit:test function test:should-be-200-status-offers()
{
unit:assert-equals(string(allegro:get-offers($test:authorizationHeader, $test:offersUrl, $test:validMap)//@status), '200')
};
(:~
: Test should pass and request should be sent as map contains only valid input parameters.
:)
declare %unit:test function test:should-pass-get-categories()
{
unit:assert(allegro:get-categories($test:authorizationHeader, $test:categoriesUrl))
};
(:~
: Test should pass and response status should be 200.
:)
declare %unit:test function test:should-be-200-status-categories()
{
unit:assert-equals(string(allegro:get-categories($test:authorizationHeader, $test:categoriesUrl)//@status), '200')
};
(:~
: Test should pass and response status should be 200.
:)
declare %unit:test function test:should-be-200-status-category-by-id()
{
unit:assert-equals(string(allegro:get-category-by-id($test:authorizationHeader, $test:categoriesUrl, 5)//@status), '200')
};
(:~
: Test should pass and response status should be 200.
:)
declare %unit:test function test:should-return-category-with-id-5()
{
unit:assert-equals(string(allegro:get-category-by-id($test:authorizationHeader, $test:categoriesUrl, 5)//id), '5')
};
(:~
: Test should pass and response status should be 200.
:)
declare %unit:test function test:should-be-200-status-category-params()
{
unit:assert-equals(string(allegro:get-category-params($test:authorizationHeader, $test:categoriesUrl, 5)//@status), '200')
};

21
XQuery Allegro API/LICENSE.md Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2019 www.release11.com
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

75
XQuery Allegro API/README.md Normal file
View File

@@ -0,0 +1,75 @@
# {$AppName}
{AppName} is a XQuery library for searching across the data shared by Allegro RESTApi.
## Getting Started
To get started download .zip file of [main repository]($link) or clone repository to your local machine.
## Prerequisites
* Java 8 or greater
* XQuery processor i.e [BaseX](http://basex.org/download/)
## Example usage
### Authorization
Before being granted with access to Allegro resources user has to [register application](https://developer.allegro.pl/auth/#app) in order to get client id and client secret.
To authorize {$AppName} uses OAuth2 Client_credentials flow. It demands access token concated with token type to be sent with every request to Allegro RESTApi as a Authorization header.
For more informations about authorization click [here](https://developer.allegro.pl/auth/#clientCredentialsFlow).
Assuming you put project files under */home* directory in order to use any function you need to create new XQuery module to execute code and import *authorization.xqm* library module with proper namespace.
Below example assumes that your module is placed under */home/src*
1) Get your base64 encoded application client id and client secret joined by ':' and pass as function argument along with authorization url.
```
xquery version "3.1";
import module namespace auth="http://release11.com/allegro/authorization" at "authorization.xqm";
let $accessToken := auth:get-access-token("https://allegro.pl/auth/oauth/token?grant_type=client_credentials","yourClientId:yourClientSecretEncoded")
```
2) Concat token type and access token to get authorization header that will be sent in every request to Allegro RESTApi and authorize your application.
```
let $authorizationHeader := auth:get-authorization-header($accessToken, "Bearer")
```
### Executing module
Below example assumes that your module is placed under */home/src*
1) In order to use any function you need to import to your module from above example *api.xqm* library module with proper namespace.
```
Xquery version "3.1";
import module namespace allegro="http://release11.com/allegro/api" at "api.xqm";
import module namespace auth="http://release11.com/allegro/authorization" at "authorization.xqm";
let $accessToken := auth:get-access-token("https://allegro.pl/auth/oauth/token?grant_type=client_credentials","yourBase64EncodedCredentials")
let $authorizationHeader := auth:get-authorization-header($accessToken, "Bearer")
```
2) The next step is to create return statement that contains function you want to use. In below example we pass categories endpoint given by Allegro, authorization header and number of category which data should be fetched.
```
return
allegro:get-category-by-id($$authorizationHeader, $categoriesUrl, 5)
```
If you are using BaseX press ctrl + enter to check the result in console. You should see xml document that represents informations about category with id 5 as shown below.
![image](https://i.imgur.com/vSn047P.png)
## Authors
Tomasz Kaleta
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details