Authentication and authorization
All requests to the Google Photos Library API 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:
- Prepare for the authorization process by doing the following:
- Register your application using the Google API Console.
- Activate the Library API and retrieve OAuth details such as a client ID and a client secret. For more information, see Get started.
To determine what scopes are suitable for your application, see Authentication and authorization scopes.
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.
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.
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.
HTTPS is required for all Library API web service requests using the following URL:
Requests made over HTTP are rejected.
For information regarding how to handle errors returned from the API, see Cloud APIs Handling errors.
Retrying failed requests
Clients should retry on
5xx errors with exponential backoff as described in
Exponential backoff. The minimum delay should be
unless otherwise documented.
429errors, the client may retry with minimum
30 s delay. For all
other errors, retry may not be applicable. Ensure your request is idempotent and see the error
message for guidance.
In rare cases, something may go wrong serving your request.You may receive a
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.
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.
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.