Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Apigee-127

Apigee-127 is a model-first toolkit for building rich, enterprise-class APIs in Node.js on your laptop. Apigee-127 is an open source project that was developed and contributed to the developer community by Apigee. 

Video: Learn about Apigee-127

 

What you need to know

  • You model and configure your APIs with the built-in, standards-compliant Swagger editor.
  • Middleware components read, validate, and process the Swagger model and automatically wire up your Apigee-127 API project.
  • Developers focus on implementing the API's core logic in Node.js.
  • Run your API entirely locally, in conjunction with Apigee Edge, or entirely on Apigee Edge or any other PaaS that supports Node.js.

Get started now!

Video: Watch a demo of the a127 command-line interface

 

Putting the API model first

To build an API with Apigee-127, you start with the Swagger editor. Use the editor to build and configure a Swagger 2.0-compliant API specification -- the blueprint for your entire API. You start the editor with the command: "a127 project edit". 

The Swagger editor for Apigee-127

The editor is intuitive to use and the configuration file is easy-to-read YAML. As you build your API, the editor builds your API docs at the same time, interactively.

Basically, you'll use the editor to "configure" everything your API needs to function in a single swagger.yaml file. 

You'll configure your API's resource endpoints (like /hello in this example):

    paths:
      /hello:
        x-swagger-router-controller: "hello_world" 
x-swagger-router-controller is a custom Swagger extension provided by Apigee for the Swagger community. It specifies the name of a Controller file that implements the logic behind the operation (for example, <project-home>/api/controllers/hello_world.js). You can read more about the extensions in "Understanding Swagger".

And, you'll define your API operation verbs and IDs, like this. (The ID maps to a method in the controller -- your API business logic.)

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

And query parameters like this:

     parameters:
        - name: search
          in: query
          description: The Query to pass to Twitter
          required: true
          type: string

And the shape of response objects:

HelloResponse:
    required:
      - name
    properties:
      name:
        type: string
      tag:
        type: string
 

And you can optionally x-a127 extensions to add enterprise-class API features like caching:

x-a127-services:
  cache:
    provider: volos-cache-memory
    options:
      name: name
      ttl: 10000
 
If you'd like to see what a complete Swagger specification looks like, check out the specification for the Apigee-127 example project on GitHub. It's an API proxy that calls the Twitter search API.

You focus on the business logic

Apigee-127 middleware components like swagger-tools do most of the heavy lifting and provide the "glue" between your Swagger model and the API implementation. The swagger-tools middleware also validates the swagger model, freeing you from the need to code parameter and other validation in your controllers. As an API developer, you can focus on implementing controller files in Node.js -- the "business logic" that defines how your API handles requests and responses:

/api/controllers/hello_world.js  
var util = require('util');

module.exports = {
  hello: hello
};

function hello(req, res) {

  var name = req.swagger.params.name.value;
  var hello = name ? util.format('Hello, %s', name) : 'Hello, stranger!';

  res.json(hello);
}
 

Video: Building a weather API 

 

Video: Building an advanced weather API

 

Video: Integrating analytics into your API

 

Further reading

For complete Apigee-127 documentation and examples, visit the  Apigee-127 documentation wiki.

Apigee-127 is all about building APIs. For tips on designing great APIs that developers will want to use, we recommend the free Web API Design ebook from Apigee. 

 

Help or comments?