What is Apigee-127?

Apigee-127 provides the tools you need to design and build Enterprise-class APIs entirely in Node.js and deploy them on any Node.js runtime system.

If you want to skip the intro and try some examples, check out the "Quick Start" topics.

In this topic, we'll introduce the parts of Apigee-127 and discuss its unique model-first approach to API development.

• Quick overview
• The Model-first Apigee-127 programming approach
• Learn from working code samples
• Watch Apigee-127 videos
• Get help

Quick overview of Apigee-127

Apigee-127 lets you model, build, and test your API model first in the intuitive, interactive Swagger editor. When you're happy with your design, you can focus on writing custom controller code (in Node.js) for each of your APIs operations.

These are the main parts of Apigee-127.

• A [Swagger 2.0 Editor] swagger-editor running locally, built for the Swagger Community by Apigee. The editor lets you design, build, test your API with easy-to-learn YAML configuration.

• [Swagger Tools] swagger-tools-github middleware for Node.js including Message Validation, Authorization and Routing. Swagger Tools extensions provide the glue between the Swagger editor configuration and your API implementation.

• [Volos.js] volos-github middleware adds value to your API with features such as Caching, Quota and OAuth 2.0. You can add Volos.js features directly in Node.js code, or, with Swagger Tools extensions, configure them directly in YAML in the Swagger editor. For example:

    x-a127-services:
      cache:     
            provider: volos-cache-memory
            options:
                name: weather-cache
                ttl: 60000
  

• [Apigee-127 Command-Line Interface] a127-cli for managing project lifecycle. Create and start projects, manage Apigee-127 accounts, deploy projects, and more. For example, to create a new project:

  a127 project create

• An easy-to-manage local Usergrid usergrid runtime and portal

• A Node.js version of [apigeetool] apigeetool-github for deploying your application to Apigee Edge

The Model-first Apigee-127 programming approach

The focus of Apigee-127 is using a standard model for building APIs. From this standard model, Apigee-127 middleware can infer a lot from your API, such as:

• What type of resources are needed to make it run
• What authorization scopes should be applied to which paths?

Combining the Node.js swagger-tools and Volos.js middleware modules, Apigee-127 enables you to quickly build robust, high quality APIs by offloading a lot of the work needed to do so. From the Swagger 2.0 model, Apigee-127 creates the server-side flows and middleware specified in the Swagger specification, leaving the core logic of the API up to API developers.

The programming flow for an Apigee-127 project looks like this:

• Define the Swagger Model using the Swagger 2.0 Editor included with Apigee-127.

• Annotate your resources and operations in the Swagger 2.0 model with the x-swagger-router-controller extension to define the name of the Controller that implements the logic behind the operation. For example:

paths:
  /hello:
    x-swagger-router-controller: "hello_world"  

• Utilize the operationId property for your operations in the Swagger 2.0 Model

    get:
      description: "Returns 'Hello' to the caller"
      operationId: "hello"

• Optionally use the Apigee-127 Swagger Extensions to define Caching, Quota and OAuth configuration:

x-a127-services:
  cache:
    provider: volos-cache-memory
    options:
      name: name
      ttl: 10000
  quota:
    provider: volos-quota-memory
    options:
      timeUnit: minute
      interval: 1
      allow: 2
  oauth2:
    provider: volos-oauth-apigee
    options:
      key: *apigeeProxyKey
      uri: *apigeeProxyUri
      validGrantTypes:
        - client_credentials
        - authorization_code
        - implicit_grant
        - password
      passwordCheck: passwordCheck

• Optionally apply Volos.js functions to individual operations to add caching, quota, and spike arrest to your API. You can integrate volos features directly into your Swagger model using the Apigee-127 Swagger Extensions or implement them programmatically in the Node.js app. Example:

  /twitter:
    x-swagger-router-controller: twitter
    x-a127-apply:
      cache: {}
      quota: {}
    get:
       ...

• Add a Swagger 2.0 security scheme to your api. For example, to add OAuth 2.0 security, configure securityDefinitions:

   securityDefinitions:
     oauth2:
       type: oauth2
       scopes:
         read: "allow read"
       flow: application
       tokenUrl: https://example.com/accessToken
  

and add OAuth 2.0 security to individual paths:

   paths:
        /hello:
           # binds a127 app logic to a route
           x-swagger-router-controller: hello_world
           x-a127-apply: {}
           get:
             description: Returns 'Hello' to the caller
             # used as the method name of the controller
             operationId: hello
             security:
             - oauth2: []

• Behind the scenes, Apigee-127 wires up your app, routing HTTP requests to specific Node.js controller files.

• At runtime the swagger-router will validate & authorize the request before sending it to the hello operation of the hello_world controller which is found in {project_home}/api/controllers/hello_world.js. By default the swagger-router looks for controllers in [project_home]/api/controllers but this can be overridden in the project.

• If configured, Volos.js Middleware will handle Caching, Quota and/or OAuth authorization

• Finally, your controller logic will be invoked according to the x-swagger-router-controller specified for the resource path and the operationId of the corresponding operation. By default the Controller should be in [project_home]/api/controllers/[x-swagger-router-controller].js

• You can develop and test your API locally using the command a127 project start

• Once you are ready to deploy your API it can run anywhere Node.js can run anywhere:

  • Apigee Edge (Requires an Apigee account. You can sign up for a free Edge account. See the note below for details.)
  • Custom servers in your datacenter
  • Other PaaS providers that support Node.js such as Heroku or Amazon Elastic Beanstalk.

However, to take advantage of the full suite of Apigee's value-added services the API should be deployed there.

Note: An Edge Trial account includes all of the features of Apigee Edge. While it does not include technical support, you are free to use the Apigee Edge Community forum to ask questions. For details about Edge Free and other pricing options, see Apigee Edge Pricing Features.

Get help

Need help using Apigee-127? Have an issue to report? See the Reporting issues and getting help.