Cloud SQL provides a REST API for administering your instancesprogrammatically. The REST API is defined by BackupRuns, Databases, Instances,Flags, Operations, SslCerts, Tiers, and Users resources. Each resource supportsmethods for accessing and working with it. For example, the Instances resourcesupports methods such as get, insert, and list. For details of all the resourcesand their methods, see theCloud SQL Admin API Reference.

Important: The Cloud SQL Admin API v1 is now generally available. It isand will continue to be compatible with the v1beta4 version. There is norequirement to migrate from v1beta4 to the v1 Admin API.

When you send requests directly to the Cloud SQL REST API, you must create thecorrect form of the request, authorize the request as an authenticated user, andprocess any responses returned. Many of the tasks in this documentation provideAPI examples usingcURL.

For more examples of using the APIs, see the page for the request in theCloud SQL Admin API Reference. Each page hasexamples calling the API in several programming languages, as well as arequest-specific Explorer to help you see what goes into a well-formed requestand what to expect in the response.

You are also using the Cloud SQL Admin API, indirectly, when you use any of thefollowing ways of administering instances:

• gcloud CLI, which contains a command-lineinterface you can use to work with your instances.

• One of theClient Libraries, suchas for Java, Python, or .NET.

• Google Cloud console, a graphical web interface.

The advantage of using these methods, especially theGoogle Cloud console, is that they can greatly simplify administering yourinstances (depending on your use case). If you are just starting out withCloud SQL, we recommend that you start with one of these tools firstbefore working with the REST API directly.

Enable the API

To use the Cloud SQL Admin API, you need to enable it:

Authorize requests

Your application needs to identify itself every time it sends a request tothe Cloud SQL Admin API, by including anAPI key with eachrequest.

Acquiring and using an API key

To acquire an API key:

1. Open theCredentials page in the Google Cloud console.
2. This API supports two types of credentials. Create whichever credentials are appropriate for your project:

   • OAuth 2.0: Whenever your application requests private user data, it must send an OAuth 2.0 token along with the request. Your application first sends a client ID and, possibly, a client secret to obtain a token. You can generate OAuth 2.0 credentials for web applications, service accounts, or installed applications.

     Note: Since this API doesn't have any methods that require OAuth 2.0 authorization, you might only need to obtainAPI keys, which are described below. However, if your application calls other APIs that require user authorization, then you still need OAuth 2.0 credentials.

     For more information, see theOAuth 2.0 documentation.

   • API keys: A request that does not provide an OAuth 2.0 token must send an API key. The key identifies your project and provides API access, quota, and reports.

     The API supports several types of restrictions on API keys. If the API key that you need doesn't already exist, then create an API key in the Console by clickingCreate credentials > API key. You can restrict the key before using it in production by clickingRestrict key and selecting one of theRestrictions.

To keep your API keys secure, follow thebest practices forsecurely using API keys.

After you have an API key, your application can append the query parameterkey=yourAPIKey to all request URLs.

The API key is safe for embedding in URLs; it doesn't need any encoding.

Note: For more information on authorizing requests, seeAuthorize Requests.

Permissions

In addition to authorization, the principal must have the required permissionsfor the API request. For more information, seeIAM permissions in Cloud SQL.

API examples

You can see examples of using the API with cURL on theREST v1 and theREST v1beta4 tabs in theHow-to Guides forthis documentation set.

Provide JSON data from a file

When you use the API with cURL, you provide property values using the commandline. If you are working with sensitive values such as passwords or securitykeys, providing them on the command line poses a security risk. For increasedsecurity, you can create a file containing the JSON data for the API call, andprovide the path to the file on the command line.

To provide JSON data to your cURL API call from a file:

1. Create a file containing everything enclosed in the single quotes for the--data field.

   Include the curly brackets, but do not include the single quotes.

2. At the command line, provide the path to the file, preceded by the@ character, as the--data parameter:

   --data@<path-to-file>/<filename>

   For example, to create a database user, you could create a filenameddata.json with the following content:

   {"host": "%", "name": "user1", "password": "abc123"}

   Then you would use the following cURL command at the command line:

   curl--header"Authorization: Bearer${ACCESS_TOKEN}"\--header'Content-Type: application/json'\--data@./data.json\-XPOST\https://www.googleapis.com/sql/v1beta4/projects/myProject/instances/myInstance/users

Work with long-running API calls

Some API calls, such as object creation, can take some time to complete. Becausethe API is asynchronous, the call returns immediately, even if the operation isstill in progress. If a subsequent API call uses the newly created object, youmust wait for the first operation to complete before proceeding.

You can wait programmatically by using the operation resource, which is returnedfor all insert calls. Provide the value of thename property to theoperationget method and inspect thestatus of the operation, When thestatus property changes fromPENDING toDONE, you can access the newly created object.

Cloud SQL and Google APIs Discovery Service

Google APIs Discovery Service is a service that you can use todiscover Google APIs. For example, when you use theGoogle APIs Explorer tool, you are using the Discovery Service. In the DiscoveryService, Cloud SQL is represented as "sqladmin" (for example:https://www.googleapis.com/discovery/v1/apis/sqladmin/v1beta4/sql.operation).This is different than the base path "sql" that you use in requests to the RESTAPI (for example:https://www.googleapis.com/sql/v1beta4/projects/example-id/instances).

Some client libraries also use the Discovery Service. In the client creationcode, be sure to use "sqladmin" to access the correct discovery document. Formore information, seeClient Libraries.

Use VPC Service Controls with the Cloud SQL Admin API

VPC Service Controls let you create a service perimeter around theCloud SQL Admin API to help mitigate dataexfiltration. The service perimeter allows free communication within theperimeter, but blocks all communication across the perimeter.

Before adding VPC Service Controls, it is recommended that you enable private IPand disable public IP on the Cloud SQL instances that you plan to add tothe service perimeter. These requirements also apply to clones, read replicas,and failover replicas.

SeeConfigure VPC Service Controls.