Understanding remote services

This topic introduces remote services and explains how to use them in your A-127 projects.

• What are remote services
• What has changed
• Using remote services
• Referencing services in Swagger files

What are remote services?

As of a127 v0.11, Apigee-127 account providers can expose remote services. The advantage of using services is that a127 can talk to them no matter where your project is deployed.

For instance, the apigee account provider currently exposes a RemoteProxy service. This service allows apps to talk to a proxy that is deployed on Apigee Edge that provides OAuth 2.0 endpoints for generating tokens and authorization codes. If you want to use Apigee OAuth, you need to bind the RemoteProxy service to your project.

Once a service is bound to a project, that service will be available no matter where you deploy it. For example, if you deploy your project to an Amazon or Heroku account, your project can access the service.

Quick example

Let's say you want to use the Apigee Edge OAuth provider in your project. This provider needs to talk to an API proxy deployed on Apigee Edge. The proxy provides endpoints for generating access tokens and performing other OAuth functions. In OAuth 2.0 speak, Apigee Edge is the authorization server implementation.

To simplify the example, we'll start by creating a brand new account and project.

###1. Create a new account.

a127 account create jdoe-02

Select apigee as the account provider. Currently, the only service available with apigee accounts is the RemoteProxy service, as you can see in the command listing below.

Note: As you can see you're given the option to create a service with the account. You can either create it now, or create it later with the command a127 service create myservice.

    a127 account create jdoe-02
    [?] Provider? apigee
    [?] Do you already have an account on apigee? Yes
    [?] Base URI? https://api.enterprise.apigee.com
    [?] Organization? docs
    [?] User Id? [email protected]
    [?] Password? ***********
    [?] Environment? prod
    [?] Virtual Hosts? default,secure
    Account wwitman-02
    ==================
    baseuri: 'https://api.enterprise.apigee.com'
    organization: docs
    username: [email protected]
    password: '******'
    environment: prod
    virtualhosts: 'default,secure'
    provider: apigee

    [?] Create account service? Yes
    [?] Service Type? RemoteProxy
    [?] Service name? myRemoteProxy
    Creating service myRemoteProxy from wwitman-02...
    Remember to bind your service to any projects that require it.
    metadata:
      account: wwitman-02
      type: RemoteProxy
    data:
      uri: 'http://docs-prod.apigee.net/myremoteproxy'
      key: p9hu87jeuFhr9pm8n2HxtewEeKLlca4KG

####What happend?

You created a new account and a new instance of the RemoteProxy service called 'myRemoteProxy'. Behind the scenes, when you created the service, a proxy called myRemoteProxy was deployed to Apigee Edge by a127. (a127 first checks to make sure a proxy of with that name wasn't already deployed. If it exists, a127 uses the existing one.) If you log in to your Apigee account and look in the API Proxies listing in the UI, you'll see it there.

In addition, a127 created a product, a developer, and a developer app on Apigee Edge. These artifacts are needed so that a127 can obtain a valid Client ID that it can use to call the remote proxy.

You can see the Client ID reflected as the key in the command output data above:

    data:
          uri: 'http://docs-prod.apigee.net/myremoteproxy'
          key: p9h18H1uFhr9pm8n2HoTtnEeKLlca4KG

If you go to Apigee Edge, and open the myremoteproxy developer app, you can see the key there. Just click Show next to the myremoteproxy product.

###2. Create a project

Just create a new default project, like this.

a127 project create myproject

###3. Bind the service to the project

a127 project bind myRemoteProxy

This step associates the service with your project. Wherever you deploy your project (or if you run it locally), a127 will use this service to verify API calls that contain OAuth 2.0 access tokens.

###4. Configure OAuth in your Swagger file

You're all set up now to add OAuth security to an a127 API. It's very simple to do by adding configurations to your project's Swagger file. For information about using OAuth in an a127 API, see the Quick Start topic: "Add Apigee OAuth".

Using remote services

Services are exposed through A-127 accounts. The first thing to do is create an account that exposes one or more services. Then, you can create a new service instance and bind it to an existing A-127 project.

To see which services are available for the currently selected A-127 account:

`a127 service types`

Use the a127 command-line tool to create, bind, list, and delete remotes services. For details, see Apigee-127 command-line reference.

The basic flow for using services is:

1. Create an Apigee-127 account: a127 account create

2. Create a service: a127 service create (required if you were not prompted to create a service during account creation)

3. Create a project: a127 project create

4. Bind the service to the project: a127 project bind

5. If necessary, deploy the project: a127 project deploy

Note: You only have to deploy the project if it was already (previously) deployed. If your running a127 locally, you do not have to deploy.

For details on these a127 commands, see "a127 reference". Or, type a127 [command] [option] -h for help. For example, a127 service create -h

Referencing services in Swagger files

To configure a service in your Swagger file, use the x-a127-config extension:

    x-a127-config:
      ApigeeRemote.key: &apigeeProxyKey CONFIGURED
      ApigeeRemote.uri: &apigeeProxyUri CONFIGURED
      ...

In this configuration:

• ApigeeRemote is the name you gave the remote service when you created it. for example: myRemoteService. Note that this name is case sensitive and must exactly match the name you used when you created it. You can get a list of service names with a127 service list.
• key and uri are service-specific values. In the case of RemoteProxy service, key and uri are required values.
• & signifies a variable that can be referenced later in the Swagger file, like this:

    oauth2:
        provider: "volos-oauth-apigee"
        options:
          ## Needed for remote proxy service
          key: *apigeeProxyKey
          uri: *apigeeProxyUri
    ...

What has changed in a127 v0.11?

After the release of services for A-127, the apigee-remote-proxy is no longer automatically created and deployed when you create an A-127 apigee account. And, the apigeeProxyKey and apigeeProxyUri values are no longer added to apigee accounts as they were before.

It's easy to create and bind services to projects, as explained below.

When you delete an account, Apigee-127 asks you if you wish to delete any services associated with that account.