Skip to content

Commit 89edd2a

Browse files
jaaufauvrejaaufauvre
committed
Updated README.md
1 parent 93934f4 commit 89edd2a

File tree

1 file changed

+64
-69
lines changed

1 file changed

+64
-69
lines changed

‎README.md‎

Lines changed: 64 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,13 @@
1515
- [Usage](#usage)
1616
* [Prerequisites](#prerequisites)
1717
* [Adding the Library to Your Project](#adding-the-library-to-your-project)
18-
* [Sample Code](#sample-code)
19-
* [Loading the Signing Key](#loading-the-signing-key)
20-
* [Creating the OAuth Authorization for a GET](#creating-the-oauth-get)
21-
* [Creating the OAuth Authorization for a POST](#creating-the-oauth-post)
22-
* [Complete code to use interceptors](#using-interceptors)
23-
24-
18+
* [Loading the Signing Key](#loading-the-signing-key)
19+
* [Creating the OAuth Authorization Header](#creating-the-oauth-authorization-header)
20+
* [Signing HTTP Client Request Objects](#signing-http-client-request-objects)
21+
* [Integrating with OpenAPI Generator API Client Libraries](#integrating-with-openapi-generator-api-client-libraries)
2522

2623
## Overview <a name="overview"></a>
27-
This is the Python version of the Mastercard compliant OAuth signature libraries.
24+
Python library for generating a Mastercard API compliant OAuth signature.
2825

2926
### Compatibility <a name="compatibility"></a>
3027
Python 3.6, 3.7
@@ -43,97 +40,95 @@ As part of this set up, you'll receive credentials for your app:
4340

4441
### Adding the Library to Your Project <a name="adding-the-library-to-your-project"></a>
4542

46-
#### PIP
47-
`pip install mastercard-oauth1-signer`
43+
```
44+
pip install mastercard-oauth1-signer
45+
```
4846

49-
#### or Clone
50-
`git clone https://github.com/Mastercard/oauth1-signer-python.git`
47+
### Loading the Signing Key <a name="loading-the-signing-key"></a>
5148

52-
Change to the repo folder, and enter :
49+
A private key object can be created by calling the `authenticationutils.load_signing_key` method:
50+
``` python
51+
signing_key = authenticationutils.load_signing_key('<insert PKCS#12 key file path>', '<insert key password>')
52+
```
5353

54-
`python3 setup.py install`
54+
### Creating the OAuth Authorization Header <a name="creating-the-oauth-authorization-header"></a>
55+
The method that does all the heavy lifting is `OAuth().get_authorization_header`. You can call into it directly and as long as you provide the correct parameters, it will return a string that you can add into your request's `Authorization` header.
5556

57+
#### POST example
5658

57-
### Sample Code <a name="sample-code"></a>
59+
```python
60+
uri = 'https://sandbox.api.mastercard.com/service'
61+
payload = 'Hello world!'
62+
authHeader = OAuth().get_authorization_header(uri, 'POST', payload, '<insert consumer key>', signing_key)
63+
```
5864

59-
The following code snippets show how to use this signing library to send messages to a Mastercard service.
65+
#### GET example
66+
```python
67+
uri = 'https://sandbox.api.mastercard.com/service'
68+
authHeader = OAuth().get_authorization_header(uri, 'GET', None, '<insert consumer key>', signing_key)
69+
```
6070

71+
### Signing HTTP Client Request Objects <a name="signing-http-client-request-objects"></a>
6172

62-
##### Imports needed for the code snippets.
63-
``` python
64-
import sys
65-
import requests
66-
from oauth1.oauth import OAuth
67-
import oauth1.authenticationutils as authenticationutils
68-
import json
69-
from urllib.parse import urlencode
70-
```
73+
Alternatively, you can use helper classes for some of the commonly used HTTP clients.
7174

72-
##### Get a signing key from the .p12 file (replace place-holder strings with values from your project in developer zone). <a name="loading-the-signing-key"></a>
73-
``` python
74-
signing_key = authenticationutils.load_signing_key('your-keyFile.p12', 'the-keystore-password')
75-
consumer_key = 'your-consumer-key-from-developer.mastercard.com'
75+
These classes will modify the provided request object in-place and will add the correct `Authorization` header. Once instantiated with a consumer key and private key, these objects can be reused.
7676

77-
baseUrl = 'https://sandbox.api.mastercard.com' # remove 'sandbox.' if calling production
78-
```
77+
Usage briefly described below, but you can also refer to the test project for examples.
7978

79+
+ [Requests: HTTP for Humans™](#requests)
8080

81-
##### To send a GET with query parameters: <a name="creating-the-oauth-get"></a>
81+
#### Requests: HTTP for Humans™ <a name="requests"></a>
8282

83-
``` python
84-
queryMap = {
85-
"Format": "XML", # change this to toggle between and XML or JSON response
86-
"Details": "offers.easysavings",
87-
"PageOffset": "0",
88-
"PageLength": "5",
89-
"Latitude": "38.53463",
90-
"Longitude": "-90.286781"
91-
}
92-
uri = baseUrl + "/merchants/v1/merchant?" + urlencode(queryMap)
93-
header = OAuth().get_authorization_header(uri, 'GET', None, consumer_key, signing_key)
94-
headers = {'Authorization': header, 'Content-Type': 'application/json'}
95-
96-
r = requests.get(uri, headers=headers)
97-
print(r.text)
83+
You can sign request objects using the `OAuthSigner` class.
84+
85+
Usage:
86+
```python
87+
uri = "https://sandbox.api.mastercard.com/service"
88+
request = Request()
89+
request.method = "POST"
90+
request.data = "..."
9891

92+
signer = OAuthSigner(consumer_key, signing_key)
93+
request = signer.sign_request(uri, request)
9994
```
10095

96+
### Integrating with OpenAPI Generator API Client Libraries <a name="integrating-with-openapi-generator-api-client-libraries"></a>
10197

102-
##### To send a POST to : <a name="creating-the-oauth-post"></a>
98+
[OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) generates API client libraries from [OpenAPI Specs](https://github.com/OAI/OpenAPI-Specification).
99+
It provides generators and library templates for supporting multiple languages and frameworks.
103100

104-
``` python
105-
uri = baseUrl + "/eop/offer/v1/search?Format=XML" # change this to toggle between and XML or JSON response
106-
reqBodyMap = {
107-
'OfferSearchCriteria': {
108-
'ItemsPerPage': 300,
109-
'Program': 'easysavings'
110-
}
111-
}
112-
reqJson = json.dumps(reqBodyMap)
113-
header = OAuth().get_authorization_header(uri, 'POST', reqJson, consumer_key, signing_key)
114-
headers = {'Authorization': header, 'Content-Type': 'application/json'}
115-
r = requests.post(uri, headers=headers, data=reqJson)
116-
print(r.text)
117-
```
101+
This project provides you with classes you can use when configuring your API client. These classes will take care of adding the correct `Authorization` header before sending the request.
118102

103+
Generators currently supported:
104+
+ [python](#python)
119105

106+
#### python <a name="python"></a>
120107

121-
##### Complete snippet to use interceptors : <a name="using-interceptors"></a>
108+
##### OpenAPI Generator
122109

123-
``` python
110+
Client libraries can be generated using the following command:
111+
```shell
112+
java -jar openapi-generator-cli.jar generate -i openapi-spec.yaml -g python -o out
113+
```
114+
See also:
115+
* [OpenAPI Generator (executable)](https://mvnrepository.com/artifact/org.openapitools/openapi-generator-cli)
116+
* [CONFIG OPTIONS for python](https://github.com/OpenAPITools/openapi-generator/blob/master/docs/generators/python.md)
117+
118+
##### Usage of the `oauth1.signer_interceptor`
119+
120+
```python
124121
import swagger_client
125122
from swagger_client.api_client import ApiClient
126123
from swagger_client.api.service_api import PostApi
127124
from oauth1.signer_interceptor import add_signing_layer
128125

129-
126+
// ...
130127
config = swagger_client.Configuration()
131128
config.host = 'https://sandbox.api.mastercard.com'
132129
client = swagger_client.ApiClient(config)
133-
134-
## Add OAuth1.0a interceptor
135-
add_signing_layer(self, client, 'your-keyFile.p12', 'the-keystore-password', 'consumer-key')
136-
130+
add_signing_layer(self, client, '<insert PKCS#12 key file path>', '<insert key password>', '<insert consumer key>')
137131
api = swagger_client.api.service_api.PostApi(client)
138132
result = api.create_resource(schema=body)
133+
// ...
139134
```

0 commit comments

Comments
 (0)