# Best practices

> [!NOTE]
> **Note:** This page focuses on technical best practices for optimal Photos API usage. For information on API policies and guidelines, refer [Photos API User Data and Developer Policy](https://developers.google.com/photos/support/api-policy).

## Authorization

All requests to the Google Photos APIs must be authorized by an authenticated user.

The details of the authorization process for OAuth 2.0 vary slightly depending
on what kind of application you're writing. The following general process
applies to all application types:

1. Prepare for the authorization process by doing the following:
   - Register your application using the [Google API Console](https://console.developers.google.com/).
   - Activate the Photos APIs and retrieve OAuth details such as a client ID and a client secret. For more information, see [Get started](https://developers.google.com/photos/overview/configure-your-app).
2. To access user data, the application makes a request to Google for a particular scope of access.
3. Google displays a consent screen to the user which asks them to authorize the application to request some of their data.
4. If the user approves, Google provides the application with an access token that expires after a brief period of time.
5. The application makes a request for the user data, attaching the access token to the request.
6. If Google determines that the request and the token are valid, it returns the requested data.

To determine what scopes are suitable for your application, see [Authorization
scopes](https://developers.google.com/photos/overview/authorization).

The process for some application types includes additional steps, such as using
refresh tokens to acquire new access tokens. For detailed information about
flows for various types of applications, see [Using OAuth 2.0 to Access Google
APIs](https://developers.google.com/identity/protocols/OAuth2).

> [!NOTE]
> **Note:** Given the security implications of getting the implementation correct, we strongly encourage you to use OAuth 2.0 libraries when interacting with Google's OAuth 2.0 endpoints. It's a best practice to use well-debugged code provided by others, and it helps you protect yourself and your users. For more information, see [OAuth 2.0 Client libraries](https://developers.google.com/identity/protocols/OAuth2#libraries).

## Caching

> [!NOTE]
> **Note:** For the Library API only

Keep data fresh.

If you need to temporarily store media (such as thumbnails, photos, or videos)
for performance reasons, don't cache it for longer than 60 minutes per our usage
guidelines.

You also shouldn't store `baseUrls`, which expire after approximately 60
minutes.

Media item IDs and album IDs that uniquely identify content in a user's library
are exempt from the caching restriction. You can store these IDs indefinitely
(subject to your application's privacy policy). Use media item IDs and album IDs
to retrieve accessible URLs and data again using the appropriate endpoints. For
more information, see [Get a media
item](https://developers.google.com/photos/library/guides/access-media-items#get-media-item) or [Listing
albums](https://developers.google.com/photos/library/guides/list#listing-albums).

If you have many media items to refresh, it might be more efficient to store the
search parameters that returned the media items and resubmit the query to reload
data.

## SSL access

HTTPS is required for all Photos APIs web service requests using the
following URL:

```
https://photoslibrary.googleapis.com/v1/service/output?parameters
```

Requests made over HTTP are rejected.

## Error handling

For information regarding how to handle errors returned from the API, see Cloud
APIs [Handling
errors](https://cloud.google.com/apis/design/errors#handling_errors).

### Retrying failed requests

Clients should retry on `5xx` errors with exponential backoff as described in
[Exponential backoff](https://developers.google.com/photos/overview/best-practices#exponential-backoff). The minimum delay should be `1 s`
unless otherwise documented.

For `429` errors, the client may retry with minimum `30s` delay. For all other
errors, retry may not be applicable. Ensure your request is idempotent and see
the error message for guidance.

### Exponential backoff

In rare cases, something may go wrong serving your request.You may receive a
`4XX` or `5XX` HTTP response code, or the TCP connection may fail somewhere
between your client and Google's server. Often, it's worthwhile to retry the
request. The follow up request may succeed when the original failed. However,
it's important to not loop, repeatedly making requests to Google's servers. This
looping behavior can overload the network between your client and Google and
cause problems for many parties.

A better approach is to retry with increasing delays between attempts. Usually,
the delay is increased by a multiplicative factor with each attempt, an approach
known as [Exponential
backoff](https://en.wikipedia.org/wiki/Exponential_backoff).

You should also be careful that there isn't retry code higher in the application
call chain that leads to repeated requests in quick succession.

## Polite use of Google APIs

Poorly designed API clients can place more load than necessary on both the
internet and on Google's servers. This section contains some best practices for
clients of the APIs. Following these best practices can help you avoid your
application being blocked for inadvertent abuse of the APIs.

### Synchronized requests

Large numbers of synchronized requests to Google's APIs can look like a
Distributed Denial of Service (DDoS) attack on Google's infrastructure, and be
treated accordingly. To avoid this, you should make sure that API requests are
not synchronized between clients.

For example, consider an application that displays the time in the current time
zone. This application will probably set an alarm in the client operating system
waking it up at the start of the minute so that the displayed time can be
updated. The application shouldn't make any API calls as part of the processing
associated with that alarm.

Making API calls in response to a fixed alarm is bad because it results in the
API calls being synchronized to the start of the minute, even between different
devices, rather than being distributed evenly over time. A poorly designed
application doing this produces a spike of traffic at sixty times normal levels
at the start of each minute.

Instead, one possible good design is to have a second alarm set to a randomly
chosen time. When this second alarm fires, the application makes calls to any
APIs it needs and stores the results. To update its display at the start of the
minute, the application uses previously stored results rather than calling the
API again. With this approach, API calls are spread evenly over time. Further,
the API calls don't delay rendering when the display is being updated.

Aside from the start of the minute, other common synchronization times you
should be careful to not target are at the start of an hour and the start of
each day at midnight.