[[help:api]]
Differences
This shows you the differences between two versions of the page.
|
help:api [2020/04/22 11:26] scotty Add Firebase Cloud Messaging registration API |
help:api [2022/10/27 19:01] (current) RichardL [OzBargain Logos] |
||
|---|---|---|---|
| Line 15: | Line 15: | ||
| | ''edit[expiry]'' | Expiry Date (format: //yyyy-mm-dd//) | | | ''edit[expiry]'' | Expiry Date (format: //yyyy-mm-dd//) | | ||
| | ''edit[coupon]'' | Coupon Code | | | ''edit[coupon]'' | Coupon Code | | ||
| + | | ''edit[category]'' | Deal Category | | ||
| - | ==== Example ==== | + | For deal category, it's last section of the URL for the deal category page. For example, |
| - | URL to submit the latest eBay Group Buy Deal. | + | * Gaming -- ''gaming'' |
| + | * Home & Garden -- ''home-garden'' | ||
| - | <code> | + | ==== Example ==== |
| - | https://www.ozbargain.com.au/deals/submit?edit[title]=eBay+Group+Buy+Deal&edit[url]=https://groupbuy.ebay.com.au/ | + | |
| - | </code> | + | |
| - | + | ||
| - | ===== OAuth 2 ===== | + | |
| - | + | ||
| - | OzBargain provides authentication / authorization with [[https://en.wikipedia.org/wiki/OAuth#OAuth_2.0|OAuth 2.0]]. Currently it's in internal alpha testing. Please use [[https://www.ozbargain.com.au/contact|Contact Form]] to request registration of a new client. | + | |
| - | + | ||
| - | ==== Endpoints ===== | + | |
| - | + | ||
| - | ^ Authorization | ''https://www.ozbargain.com.au/oauth/authorize'' | | + | |
| - | ^ Access Token | ''https://www.ozbargain.com.au/oauth/token'' | | + | |
| - | ^ Login | ''https://www.ozbargain.com.au/oauth/login'' | | + | |
| - | ^ User Info | ''https://www.ozbargain.com.au/oauth/authorize'' | | + | |
| - | + | ||
| - | ==== Workflow ==== | + | |
| - | + | ||
| - | Assume | + | |
| - | + | ||
| - | * ''client_id=testapp'' | + | |
| - | * ''client_secret=testsecret'' | + | |
| - | * ''<nowiki>redirect_uri=testapp://example.com/</nowiki>'' | + | |
| - | To request authorization from a logged in user, redirect the user to this URL: | + | URL to submit the latest eBay Group Buy Deal to Electrical & Electronics category |
| <code> | <code> | ||
| - | https://www.ozbargain.com.au/oauth/authorize?client_id=testapp&response_type=code&state=test | + | https://www.ozbargain.com.au/deals/submit?edit[title]=eBay+Group+Buy+Deal&edit[url]=https://groupbuy.ebay.com.au/&edit[category]=electrical-electronics |
| </code> | </code> | ||
| - | Note: | + | ===== OzBargain Logos ===== |
| - | * ''state'' needs to be present and best to be a random string that can be verified later. | + | [[https://files.delvu.com/images/ozbargain/logo/Logo.png|{{https://files.delvu.com/images/ozbargain/logo/Logo.png?200|}}]] |
| - | * If ''redirect_uri'' is not configured on the OzBargain Authorization Controller, it can be passed in as part of URL using ''redirect_uri'' in query string parameter. | + | |
| - | After the user accepted the authorization request, OzBargain will then redirect to | + | (OzBargain.com.au Logo) |
| - | <code>testapp://example.com/?code=<authorization_token>&state=test</code> | + | [[https://files.delvu.com/images/ozbargain/logo/Logo.png|png]] | [[https://files.delvu.com/images/ozbargain/logo/Logo.svg|svg]] |
| - | Your website / app can then use ''<authorization_token>'' to request access token to access OzBargain on behalf of the user. To request access token, HTTP POST to the following URL: | ||
| - | <code> | + | ---- |
| - | https://www.ozbargain.com.au/oauth/token | + | |
| - | </code> | + | |
| - | with | ||
| - | <code> | + | [[https://files.delvu.com/images/ozbargain/logo/Square.png|{{https://files.delvu.com/images/ozbargain/logo/Square.png?200|}}]] |
| - | client_id=testapp&client_secret=testsecret&grant_type=authorization_code&code=<authorization_token> | + | |
| - | </code> | + | |
| - | as POST data (''Content-Type: application/x-www-form-urlencoded''). If successful, OAuth server will return the access token in JSON. | + | (Just a simple [Oz]) |
| - | <code> | + | [[https://files.delvu.com/images/ozbargain/logo/Square.png|png]] | [[https://files.delvu.com/images/ozbargain/logo/Square.svg|svg]] |
| - | { | + | |
| - | "access_token": "e8cc0eaee04c0dbe19ced626ffc4aefac2770b67", | + | |
| - | "expires_in": 7200, | + | |
| - | "refresh_token": "87eebc12677da143d2757621b65f4f98aebe0489", | + | |
| - | "scope": null, | + | |
| - | "token_type": "Bearer" | + | |
| - | } | + | |
| - | </code> | + | |
| - | ''access_token'' can be used by your website / app to access OzBargain resources as that user. ''refresh_token'' can be used to generate a new access token after the initial one has expired. Note that by default, OzBargain has 2 hour expiry for ''access_token'' and 2 week expiry for ''refresh_token''. | + | ---- |
| - | ==== Login via Access Token ==== | + | [[https://files.delvu.com/images/ozbargain/logo/Square%20Flat.png|{{https://files.delvu.com/images/ozbargain/logo/Square%20Flat.png?200|}}]] |
| - | You are able to log into the OzBargain website using access token obtained from OAuth. Use the following URL: | ||
| - | <code> | + | (The flat / non-gradient version of [Oz]) |
| - | https://www.ozbargain.com.au/oauth/login?access_token=<access_token>&destination=<destination> | + | |
| - | </code> | + | |
| - | Parameters: | + | [[https://files.delvu.com/images/ozbargain/logo/Square%20Flat.png|png]] | [[https://files.delvu.com/images/ozbargain/logo/Square%20Flat.svg|svg]] |
| - | * **''access_token''** -- 40 character access token obtained from work-flow above. | + | ---- |
| - | * **''destination''** -- OzBargain page to be redirected to after logging in. For example ''node/12345'' or ''<front>'' for Front Page. | + | |
| - | Note that if ''access_token'' is invalid, the browser will be redirected to user-login page with error message. | + | [[https://files.delvu.com/images/ozbargain/logo/512maskavatar.jpg|{{https://files.delvu.com/images/ozbargain/logo/512maskavatar.jpg?200|}}]] |
| - | ==== Bearer Authentication ==== | ||
| - | Your website / app can issue authenticated API calls or download RSS pages //as a logged in user// using Bearer Authentication. Add the following header to your request: | + | (Mask wearing avatar) |
| - | + | ||
| - | <code> | + | |
| - | Authorization: Bearer <access_token> | + | |
| - | </code> | + | |
| - | + | ||
| - | Note that if ''access_token'' is invalid, HTTP response "403 Access Denied" will be returned. | + | |
| - | + | ||
| - | ==== Refresh Access Token ==== | + | |
| - | + | ||
| - | As default ''access_token'' expires after 2 hours, you will need to have user authorise again, or use the refresh token to obtain a new set of access/refresh token (before the existing refresh token expires). To get a new refresh token, HTTP POST to the following URL: | + | |
| - | + | ||
| - | <code> | + | |
| - | https://www.ozbargain.com.au/oauth/token | + | |
| - | </code> | + | |
| - | + | ||
| - | with POST data: | + | |
| - | + | ||
| - | <code> | + | |
| - | client_id=testapp&client_secret=testsecret&grant_type=refresh_token&refresh_token=<refresh_token> | + | |
| - | </code> | + | |
| - | + | ||
| - | If ''<refresh_token>'' is valid, the following JSON will be returned: | + | |
| - | + | ||
| - | <code> | + | |
| - | { | + | |
| - | "access_token": "ccbb1f1b98660c469bdaf7280e09d5134263c35a", | + | |
| - | "expires_in": 7200, | + | |
| - | "refresh_token": "cda24fea9a82ff69844416d2ea4b32bb9efe5bf1", | + | |
| - | "scope": null, | + | |
| - | "token_type": "Bearer" | + | |
| - | } | + | |
| - | </code> | + | |
| - | + | ||
| - | Note that ''<refresh_token>'' is one-use only, and you must grab the updated ''<access_token>'' and ''<refresh_token>''. | + | |
| - | + | ||
| - | ==== Get User Info ==== | + | |
| - | + | ||
| - | To retrieve information about OzBargain user associated with an ''access_token'', issue an HTTP GET request on the following URL: | + | |
| - | + | ||
| - | <code> | + | |
| - | https://www.ozbargain.com.au/oauth/resource?access_token=<access_token> | + | |
| - | </code> | + | |
| - | + | ||
| - | JSON result will be returned, and if successful: | + | |
| - | + | ||
| - | <code> | + | |
| - | { | + | |
| - | "success": true, | + | |
| - | "message": "OAuth2 token verified.", | + | |
| - | "user": { | + | |
| - | "uid": 2, | + | |
| - | "name": "testuser", | + | |
| - | "email": "[email protected]", | + | |
| - | "role": "User", | + | |
| - | "penalised": false | + | |
| - | } | + | |
| - | } | + | |
| - | </code> | + | |
| - | + | ||
| - | ===== Firebase Cloud Messaging ===== | + | |
| - | + | ||
| - | OzBargain is currently testing [[https://firebase.google.com/docs/cloud-messaging|Firebase cloud]] messaging integration. Here are some support API. | + | |
| - | + | ||
| - | To register/activate/deactivate an instance for message delivery, use the following URL as endpoint. Use Bearer authorization with OAuth2 access token. ''<uid>'' is the numeric number of the user to update the setting, and it must be the same as the authenticated user. | + | |
| - | + | ||
| - | <code> | + | |
| - | https://www.ozbargain.com.au/ozbapi/user/<uid>/firebase | + | |
| - | </code> | + | |
| - | + | ||
| - | Parameters are send in via POST data in URL encoded form. | + | |
| - | + | ||
| - | ^ Parameter ^ Value ^ | + | |
| - | | ''code'' | Instance ID | | + | |
| - | | ''name'' | Name of this instance (optional)\\ For example "Android Phone" | | + | |
| - | | ''active'' | 0 or 1 to activate/deactivate already registered instance (optional) | | + | |
| - | + | ||
| - | ==== Example ==== | + | |
| - | + | ||
| - | <code> | + | |
| - | $ curl -F 'code=1234567890' -F 'name=TestClient' \ | + | |
| - | -H 'Authorization: Bearer 0987654321' | + | |
| - | https://www.ozbargain.com.au/ozbapi/user/2/firebase | + | |
| - | {"result":true,"message":"Instance has been registered"} | + | |
| - | + | ||
| - | $ curl -F 'code=1234567890' -F 'active=0' \ | + | |
| - | -H 'Authorization: Bearer 0987654321' | + | |
| - | https://www.ozbargain.com.au/ozbapi/user/2/firebase | + | |
| - | {"result":true,"message":"Instance has been deactivated"} | + | |
| - | </code> | + | |
| - | + | ||
| - | ===== OzBargain Logos ===== | + | |
| - | + | ||
| - | [[https://files.delvu.com/images/ozbargain/logo/Logo.png|{{https://files.delvu.com/images/ozbargain/logo/Logo.png?200|}}]] | + | |
| - | + | ||
| - | (OzBargain.com.au Logo) | + | |
| - | + | ||
| - | [[https://files.delvu.com/images/ozbargain/logo/Logo.png|png]] | [[https://files.delvu.com/images/ozbargain/logo/Logo.svg|svg]] | + | |
| + | [[https://files.delvu.com/images/ozbargain/logo/512maskavatar.jpg|jpg]] | [[https://files.delvu.com/images/ozbargain/logo/512maskavatar.xcf|xcf]] | ||
| ---- | ---- | ||
| + | [[https://files.delvu.com/images/ozbargain/logo/512avatar.jpg|{{https://files.delvu.com/images/ozbargain/logo/512avatar.jpg?200|}}]] | ||
| - | [[https://files.delvu.com/images/ozbargain/logo/Square.png|{{https://files.delvu.com/images/ozbargain/logo/Square.png?200|}}]] | ||
| - | (Just a simple [Oz]) | + | (Default avatar (no mask)) |
| - | [[https://files.delvu.com/images/ozbargain/logo/Square.png|png]] | [[https://files.delvu.com/images/ozbargain/logo/Square.svg|svg]] | + | [[https://files.delvu.com/images/ozbargain/logo/512avatar.jpg|jpg]] |
| - | ---- | ||
| - | [[https://files.delvu.com/images/ozbargain/logo/Square%20Flat.png|{{https://files.delvu.com/images/ozbargain/logo/Square%20Flat.png?200|}}]] | ||
| - | |||
| - | |||
| - | (The flat / non-gradient version of [Oz]) | ||
| - | |||
| - | [[https://files.delvu.com/images/ozbargain/logo/Square%20Flat.png|png]] | [[https://files.delvu.com/images/ozbargain/logo/Square%20Flat.svg|svg]] | ||
Last edited by RichardL on 2022/10/27 19:01