alpaca

Api Libraries Powered And Created by Alpaca

Tired of maintaining API libraries in different languages for your website API? This is for you

You have an API for your website but no API libraries for whatever reason? This is for you

You are planning to build an API for your website and develop API libraries? This is for you

You define your API according to the format given below, alpaca builds the API libraries along with their documentation. All you have to do is publishing them to their respective package managers.

Join us at gitter if you need any help.

Installation

You can download the binaries (v0.2.1)

Architecture i386 [ linux / windows / darwin / freebsd / openbsd / netbsd / plan9 ]
Architecture amd64 [ linux / windows / darwin / freebsd / openbsd / netbsd ]
Architecture arm [ linux / freebsd / netbsd ]

Or by using deb packages (v0.2.1)

[ i386 / amd64 / armhf ]

Or by using golang (v1.2)

# Clone the project into your golang workspace
$ git clone git://github.com/pksunkara/alpaca
$ cd alpaca

# Install program
$ make && make install

Examples

You can find some api definitions in the examples directory. The api libraries generated are at https://github.com/alpaca-api

Completed api definitions are buffer.

Usage

$ alpaca </path/to/dir>

The path here should be a directory with api.json, pkg.json, doc.json

Usage:
  alpaca [options] <dir>

Application Options:
  -v, --version    Show version information

Language Options:
      --no-php     Do not write php library
      --no-python  Do not write python library
      --no-ruby    Do not write ruby library
      --no-node    Do not write node library

Help Options:
  -h, --help       Show this help message

Please remove the comments when actually using these json files

pkg.json

All the following fields are required unless mentioned.

{
  "name": "Example", // Name of the api (also used as class name for the library)
  "package": "example-alpaca", // Name of the package
  "version": "0.1.0", // Version of the package
  "url": "https://exampleapp.com", // URL of the api
  "keywords": ["alpaca", "exampleapp", "api"], // Keywords for the package
  "official": false, // Are the api libraries official?
  "author": {
    "name": "Pavan Kumar Sunkara", // Name of the package author
    "email": "pavan.sss1991@gmail.com", // Email of the package author
    "url": "http://github.com/pksunkara" // URL of the package author
  },
  "git": { // Used in the package definition
    "site": "github.com", // Name of the git website
    "user": "alpaca-api", // Username of the git website
    "name": "buffer" // Namespace of the git repositories
  },
  "license": "MIT", // License of the package
  "php": { // Required only if creating php api lib
    "vendor": "pksunkara" // Packagist vendor name for the package
  },
  "python": { // Required only if creating python api lib
    "license": "MIT License" // Classifier of the license used for the module
  }
}

api.json

All the following fields are required unless mentioned.

{
  "base": "https://exampleapp.com", // Base URL of the api
  "base_as_arg": true, // Force Base URL to be an argument in generated clients [optional] (default: false)
  "version": "v1", // Default version for the api (https://api.example.com{/version}/users) [optional]
  "no_verify_ssl": true, // Do not verify SSL cert [optional] (default: false)
  "authorization": { // Authorization strategies
    "need_auth": true, // Authentication is compulsory [optional] (default: false)
    "basic" : true, // Basic authentication [optional] (default: false)
    "header": true, // Token in authorization header [optional] (default: false)
    "header_prefix": "oompaloompa", // The first word in header if using token auth header [optional] (default: token)
    "oauth" : true // OAUTH authorization [optional] (default: false)
  },
  "request": { // Settings for requests to the api
    "formats": { // Format of the request body
      "default": "form", // Default format for the request body [optional] (default: raw)
      "form": true, // Support form-url-encoded? [optional] (default: false)
      "json": true // Support json? [optional] (default: false)
    }
  },
  "response": { // Settings for responses from the api
    "suffix": true, // Should the urls be suffixed with response format? [optional] (default: false)
    "formats": { // Format of the response body
      "default": "json", // Default response format. Used when 'suffix' is 'true'
      "html": true, // Support html? [optional] (default: false)
      "json": true // Support json? [optional] (default: false)
    }
  },
  "error": { // Required if response format is 'json'
    "message": "error" // The field to be used from the response body for error message
  },
  "class": { // The classes for the api
    "users": { // Name of a class of the api
      "args": ["login"], // Arguments required for the api class [optional]
      "profile": { // Name of a method of the api
        "path": "/users/:login/:type", // URL of the api method
        "method": "post", // HTTP method of the api method [optional] (default: get)
        "params": [ // Parameters for the api method [optional]
          {
            "name": "type", // Name of the parameter
            "required": true, // The parameter will become an argument of api method [optional] (default: false)
            "url_use": true // This parameter is only used to build url [optional] (default: false)
          },
          {
            "name": "bio",
            "required": true
          }
        ]
      }
    }
  }
}

doc.json

The following is filled according to the entries in api.json

{
  "users": { // Name of a class of the api
    "title": "Users", // Title of the api class
    "desc": "Returns user api instance", // Description of the api class
    "args": { // Arguments of the api class
      "login": { // Name of the argument
        "desc": "Username of the user", // Description of the argument
        "value": "pksunkara" // Value of the argument in docs
      }
    },
    "profile": { // Name of a method of the api
      "title": "Edit profile", // Title of the api method
      "desc": "Edit the user's profile", // Description of the api method
      "params": { // Parameter of the api class
        "bio": { // Name of the parameter
          "desc": "Short bio in profile", // Description of the parameter
          "value": "I am awesome!" // Value of the parameter in docs
        },
        "type": {
          "desc": "Circle of the profile",
          "value": "friends"
        }
      }
    }
  }
}

Request formats

Supported request formats are raw, form, json. The format raw is always true.

This means, the body set in the options when calling an API method will be able to be encoded according to the respective request_type

If set to raw, body is not modified at all

Response formats

Supported response formats are html, json.

Authorization strategies

Supported are basic, header, oauth

Language Versions

Supported programming language versions are:

Language	V	E	R	S	I	O	N
node	0.8	0.9	0.10	0.11	0.12
php	5.4	5.5
python	2.6	2.7	3.2	3.3
ruby	1.8.7	1.9.1	1.9.2	1.9.3	2.0.0	2.1.0	2.1.1

Package Managers

Language	Package Manager
node	https://npmjs.org
php	https://packagist.org
python	https://pypi.python.org
ruby	https://rubygems.org

Testing

Check here to learn about testing.

Contributors

Here is a list of Contributors

I accept pull requests and guarantee a reply back within a day

TODO

You get internet points for pull requesting the following features.

Responses

Requests

HTTP Method Overloading
What about file uploads?

API

Check returned status code
Special case for 204:true and 404:false

Libraries

Pagination support
Classes inside classes (so on..)
Validations for params/body in api methods
Allow customization of errors
Tests for libraries (lots and lots of tests)

Readme

Optional params available
Return types of api calls

Comments

The descriptions should be wrapped
Align @param descriptions

Formats

Languages

Support Java
Support Go
Support Clojure
Support Rust
Support Swift
Support C, C++, Perl, Scala, C#, Erlang, Lua, Haskell, D, Julia, Groovy
Build cli tool for APIs (bash? python? go?)

Support Projects

Alternatively, you can write your own converter from alpaca.json to the following

Convert into API Blueprint
Convert into Swagger

License

MIT/X11

Bug Reports

Report here. Guaranteed reply within a day.

Contact

Pavan Kumar Sunkara (pavan.sss1991@gmail.com)

Follow me on github, twitter

pksunkara / alpaca

readme