Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

updated getting started links #123

Merged
merged 2 commits into from
Jul 15, 2024
Merged

updated getting started links #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5dd63ae
Update getting started links (#2)
jhauga Jul 15, 2024
bce65ce
updated getting started links
jhauga Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# pinterest/api-quickstart

Code that makes it easy to get started with the Pinterest API.
Code that makes it easy to get started with the Pinterest API. For full details see the [getting started](https://developers.pinterest.com/docs/overview/welcome/) documentation.

## Purpose

Expand All @@ -12,8 +12,8 @@ This quickstart used to support Pinterest API version v3 and v4, but that code h

1. Set up the environment with your credentials (app ID and secret). This configuration works with the code in all of the language-specific directories.

* Get an application ID and secret by hitting the "Connect app" button at [https://developers.pinterest.com/apps/](https://developers.pinterest.com/apps/). You may first need to follow the steps required to [request trial access](https://developers.pinterest.com/docs/getting-started/getting-access/) to the Pinterest API. You can also find step-by-step instructions on the [Glitch-based tutorial](https://pinterest-oauth-tutorial.glitch.me/).
* Once your app is connected, hit the Manage button for the app on [https://developers.pinterest.com/apps/](https://developers.pinterest.com/apps/) to see your App id and App secret key. (Click the Show key button to see the App secret key.)
* Get an application ID and secret by hitting the "Connect app" button at the [apps dashboard](https://developers.pinterest.com/apps/). You may first need to follow the steps required to [request trial access](https://developers.pinterest.com/docs/getting-started/getting-access/) to the Pinterest API. You can also find step-by-step instructions on the [Glitch-based tutorial](https://pinterest-oauth-tutorial.glitch.me/).
* Once your app is connected, hit the Manage button for the app on the [apps dashboard](https://developers.pinterest.com/apps/) to see your App id and App secret key. (Click the Show key button to see the App secret key.)
* Put your App ID and App secret key in an environment script file.
```
$ cd common/scripts
Expand All @@ -22,7 +22,7 @@ This quickstart used to support Pinterest API version v3 and v4, but that code h
$ cd ../..
```
* Configure the OAuth2 redirect URI required by this code.
1. Click on the Manage button for your application at [https://developers.pinterest.com/apps/](https://developers.pinterest.com/apps/).
1. Click on the Manage button for your application at the [apps dashboard](https://developers.pinterest.com/apps/).
2. In the box labeled "Redirect link," enter `http://localhost:8085/`.
3. Hit the return (enter) key or the Add button to save redirect URI (link).
* Run the environment set-up script and verify the results.
Expand Down Expand Up @@ -53,7 +53,7 @@ This quickstart used to support Pinterest API version v3 and v4, but that code h

## OAuth 2.0 Authorization

Access to Pinterest APIs via User Authorization requires following a flow based on [OAuth 2.0](https://tools.ietf.org/html/rfc6749). To learn about how to use OAuth 2.0 with the Pinterest API, check out the [Glitch-based tutorial](https://pinterest-oauth-tutorial.glitch.me/). For details regarding OAuth, please refer to our [v5 developer docs](https://developers.pinterest.com/docs/getting-started/authentication/). The code in this repo demonstrates how to initiate the flow by starting a browser, and then handling the OAuth redirect to the development machine (localhost). The browser is used to obtain an authorization code, and then the code invoked by the redirect exchanges the authorization code for an access token.
Access to Pinterest APIs via User Authorization requires following a flow based on [OAuth 2.0](https://tools.ietf.org/html/rfc6749). To learn about how to use OAuth 2.0 with the Pinterest API, check out the [Glitch-based tutorial](https://pinterest-oauth-tutorial.glitch.me/). For details regarding OAuth, please refer to our [v5 developer docs](https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/). The code in this repo demonstrates how to initiate the flow by starting a browser, and then handling the OAuth redirect to the development machine (localhost). The browser is used to obtain an authorization code, and then the code invoked by the redirect exchanges the authorization code for an access token.

An access token is used to authenticate most API calls. In general, access tokens are valid for relatively long periods of time, in order to avoid asking users to go through the OAuth flow too often. When an access token expires, it is possible to refresh the token -- a capability that the code in this repo also demonstrates.

Expand Down
3 changes: 2 additions & 1 deletion bash/scripts/get_access_token.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ echo 'getting auth_code...'

# Specify the scopes for the user to authorize via OAuth.
# This example requests typical read-only authorization.
# For more information, see: https://developers.pinterest.com/docs/getting-started/authentication/
# For more information, see:
# https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/#requesting-the-right-scopes-for-your-app
SCOPE="user_accounts:read"

# This call opens the browser with the oauth information in the URI.
Expand Down
2 changes: 1 addition & 1 deletion nodejs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ Valid OAuth 2.0 scopes for Pinterest API version v5:
user_accounts:read Read access to user accounts

For more information, see:
https://developers.pinterest.com/docs/getting-started/scopes/
https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/#pinterest-scopes
```

### [refresh_example.js](./scripts/refresh_example.js)
Expand Down
98 changes: 49 additions & 49 deletions php/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,49 @@
# PHP Quickstart

PHP code that demonstrates the basics of how to use the Pinterest API.

## Quick Start

1. Install PHP and check the version. The code for this repo has been tested with PHP version 8.

1. Follow the directions in the README at the top level of this repo for configuring your application ID and application secret.

3. From the top of this repo, change your working directory to this directory: `cd php`

4. Set up the shell environment.

```
$ . ../common/scripts/api_env
```

5. Run the php server in this directory on the port configured when following the instructions in the top-level README.

```
$ php -S localhost:8085
```
6. [Click here](http://localhost:8085/) or point your browser at http://localhost:8085.

## Troubleshooting

* If you see the error `Warning: session_start(): Cannot start session when headers already sent`, you're likely using a version of PHP lower than 8. This example requires PHP version 8, so you'll need to install the latest version.

* If the redirect to Pinterest returns a 400 error that says "Oops! You must pass a value for client_id," check to verify that the `api_env` script has been run properly.
```
$ env | grep PINTEREST_APP_ID
PINTEREST_APP_ID=<your application id>
```

* If the demo code that fetches user account information fails, check to make sure that the user account has a profile picture and at least one saved Pin.

## Code Conventions

This PHP code needs to pass the [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) linter using
the default PEAR coding standard. To run the linter, first install the PHP_CodeSniffer. For example, on MacOS
configured with HomeBrew, install with:
```
brew install php-code-sniffer
```
Then, run the linter with `make lint` or `phpcs <filename>`. Run the code fixer
with `make lint-fix` or `phpcbf <filename>`.

`make lint` will be run automatically for pull requests.
# PHP Quickstart
PHP code that demonstrates the basics of how to use the Pinterest API.
## Quick Start
1. Install PHP and check the version. The code for this repo has been tested with PHP version 8.
1. Follow the directions in the README at the top level of this repo for configuring your application ID and application secret.
3. From the top of this repo, change your working directory to this directory: `cd php`
4. Set up the shell environment.
```
$ . ../common/scripts/api_env
```
5. Run the php server in this directory on the port configured when following the instructions in the top-level README.
```
$ php -S localhost:8085
```
6. [Click here](http://localhost:8085/) or point your browser at `http://localhost:8085`.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the only line edited. Copied and pasted full contents from editor to GitHub may have caused new line difference.

## Troubleshooting
* If you see the error `Warning: session_start(): Cannot start session when headers already sent`, you're likely using a version of PHP lower than 8. This example requires PHP version 8, so you'll need to install the latest version.
* If the redirect to Pinterest returns a 400 error that says "Oops! You must pass a value for client_id," check to verify that the `api_env` script has been run properly.
```
$ env | grep PINTEREST_APP_ID
PINTEREST_APP_ID=<your application id>
```
* If the demo code that fetches user account information fails, check to make sure that the user account has a profile picture and at least one saved Pin.
## Code Conventions
This PHP code needs to pass the [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) linter using
the default PEAR coding standard. To run the linter, first install the PHP_CodeSniffer. For example, on MacOS
configured with HomeBrew, install with:
```
brew install php-code-sniffer
```
Then, run the linter with `make lint` or `phpcs <filename>`. Run the code fixer
with `make lint-fix` or `phpcbf <filename>`.
`make lint` will be run automatically for pull requests.
4 changes: 2 additions & 2 deletions python/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Here is a list of common arguments that work with all scripts:
Below you will find a description of each script along with an example of its help documentation.

### [get_access_token.py](./scripts/get_access_token.py)
Quick start code that demonstrates the OAuth 2.0 flow and tests the authentication by reading the user profile using the `/v5/user_account` [endpoint](https://developers.pinterest.com/docs/api/v5/#tag/user_account). Running this script with the `-w` parameter (`./scripts/get_access_token.py -w`) stores the access token in `../common/oauth_tokens/access_token.json` for future use. Use `-w` parameter in combination with the `-a` (access token name) parameter to store separate access tokens for different purposes. When requesting an access token without specifying scopes, the script will default to `user_accounts:read` `pins:read` and `boards:read`. To see a complete list of scopes, refer to the Enums in [`./src/v5/oauth_scope.py`](./src/v5/oauth_scope.py). You can also run `./scripts/get_access_token.py -s help` to see the scopes.
Quick start code that demonstrates the OAuth 2.0 flow and tests the authentication by reading the user profile using the `/v5/user_account` [endpoint](https://developers.pinterest.com/docs/api/v5/#tag/user_account). Running this script with the `-w` parameter (`./scripts/get_access_token.py -w`) stores the access token in `../common/oauth_tokens/access_token.json` for future use. Use `-w` parameter in combination with the `-a` (access token name) parameter to store separate access tokens for different purposes. When requesting an access token without specifying scopes, the script will default to `user_accounts:read` `pins:read` and `boards:read`. To see a complete list of scopes, refer to the Enums in [`./src/oauth_scope.py`](./src/oauth_scope.py). You can also run `./scripts/get_access_token.py -s help` to see the scopes.
davidchaiken marked this conversation as resolved.
Show resolved Hide resolved

<!--gen-->
```
Expand Down Expand Up @@ -99,7 +99,7 @@ Valid OAuth 2.0 scopes for Pinterest API version v5:
user_accounts:read Read access to user accounts

For more information, see:
https://developers.pinterest.com/docs/getting-started/scopes/
https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/#pinterest-scopes
```

### [refresh_example.py](./scripts/refresh_example.py)
Expand Down
2 changes: 1 addition & 1 deletion python/src/access_token.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ def oauth(self, scopes=None, client_credentials=False):
"""
Execute the OAuth 2.0 process for obtaining an access token.
For more information, see IETF RFC 6749: https://tools.ietf.org/html/rfc6749
and https://developers.pinterest.com/docs/getting-started/authentication/
and https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/
"""
if not scopes:
scopes = [Scope.READ_USERS, Scope.READ_PINS, Scope.READ_BOARDS]
Expand Down
4 changes: 2 additions & 2 deletions python/src/oauth_scope.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@


# Enumerate the valid OAuth scopes.
# For details, see: https://developers.pinterest.com/docs/getting-started/scopes/
# For details, see: https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/#pinterest-scopes
davidchaiken marked this conversation as resolved.
Show resolved Hide resolved
class Scope(Enum):
READ_ADS = "ads:read"
WRITE_ADS = "ads:write"
Expand Down Expand Up @@ -61,5 +61,5 @@ def print_scopes():
user_accounts:read Read access to user accounts

For more information, see:
https://developers.pinterest.com/docs/getting-started/scopes/"""
https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/#pinterest-scopes"""
)
2 changes: 1 addition & 1 deletion python/src/user_auth.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ def get_auth_code(api_config, scopes=None, refreshable=True):
"""
This flow will typically be interrupted by the developer if the
OAuth did not work in the browser. For details, see the documentation:
https://developers.pinterest.com/docs/getting-started/authentication/
https://developers.pinterest.com/docs/getting-started/authentication-and-scopes/
https://developers.pinterest.com/docs/redoc/#section/User-Authorization/Start-the-OAuth-flow-%28explicit-server-side%29
""" # noqa: E501 because the long URL is okay
sys.exit("\nSorry that the OAuth redirect didn't work out. :-/")
Expand Down
Loading