API proxy

Used to create a layer between your API and Bitbucket to provide the heavy lifting for authentication, parameter substitution, object hydration, and other services. You can read about how Bitbucket's API proxy works and how to use it in the Proxy module guide.

Sample descriptor JSON

You create the proxy connection when you map a URL pattern to a specific destination URL in your app descriptor. The simplest form of this is:

1
2
"modules": {
    "proxy": {
        "/proxy-example/{repository}": {
            "destination": "/proxy-example?name={repository.owner.display_name}", // required
            "methods": { ... }, // optional
            "conditions": { ... }, // optional
            "scopes": { ... } // optional
        }
    }
}

In this example, the context parameter {repository} needs to be captured using the UUID. However, for objects that belong to another object -- like how a repository belongs to a user or team -- the parent object needs to be resolved in order to resolve a child object. Read more about this in the subsection of the article about Object hydration, Capturing the parent object of the object you're capturing.

Path definitions

The path definition will be the URL that's transformed by Bitbucket and is served to clients.

Properties


`destination`
	Type	string
	Required	Yes
	Description	The destination for a proxy path. This can be a fully qualified, absolute URL, or it can be just a path. In case of the latter, it is concatenated to the base URL. Destination URLs can contain Connect context parameters that will be substituted at runtime with request properties.
PROPERTIES
`methods`	Type	string
	Required	No
	Description	The HTTP methods GET, PUT, POST and DELETE can be defined inside the `methods` property in order to explicitly define which methods are can be forwarded. Within this method definition, `destination`, `scopes` or `conditions` can be defined as properties to override the properties at the top level for the path definition.
`scopes`	Type	[Scopes]
	Required	No
	Description	The scopes property can be used to define the scopes a request needs in order to be able to access the resource. For more details refer to the list of Rest API Scopes.
`conditions`	Required	No
	Type	[Simple condition, Composition condition]
	Description	An array of conditions used to restrict access to the resource.

Declaring conflicting conditions or scopes

If nested scopes or conditions conflict, values declared by a child element will override values declared by parent elements. See the Restrict HTTP methods example in the API proxy module guide for an example of conflicting nested conditions.