pksunkara / alpaca Goto Github PK

I installed the .deb package on Ubuntu successfully, and copied over the buffer example folder. When I run alpaca on the folder, i don't get any error message, but the API wrappers don't appear in the directory with the original Alpaca files or anywhere else that I can see.

For the generated PHP code, looking at AuthHandler.php line 58, the header generated is Authorization: token %s. This is not compatible with all API servers. In my case, I need to change token to Token (in other words, capitalize the word 'token') for the API calls to work.

Propose one of two changes:

1. If the standard is to use the capitalized version of the word 'Token', simply change the generated code accordingly.
   Or:
2. Add the ability to customize the word 'token' via the api.json configuration file.

Presumably the change would be applicable generally, i.e. to all generated client code in all languages (not just PHP).

I got an API for https://catapult.inetwork.com/pages/home.jsf they are like twilio but cheaper I think. Can we include this as an example? If so, I'm happy to send a PR for it

Better generated documentation too.

alpaca.json is basically just a concatenation of all those 3 JSON objects in their respective keys. api, pkg and doc.

Hi,

First, great project, great idea! :)

I do have an issue with the ease of keeping documentation text in a separate doc.js file, which means there is the need to stay synchronized with the "class" portion of the api.js and the order of params defined in there.

Currently, params are defined as an array. This means it's not possible to add code-relevant information to each param (eg, "type" for typed/hinted languages such as PHP), but also means that if the order of parameters is changed, the documentation becomes incorrect.

I would suggest changing api.js so that instead of this:

    "create_update": {
            ...
            "params": ["text", "profile_ids"]
     }

You'd instead write the params field as an object, and could also provide info immediately in there. I also suggest adding a type field, which if used can generate type hints for the method signatures. So, in the api.js file you'd write:

    "create_update": {
            ...
            "params": {
                "text": {
                     "type": "string",  // optional
                     "desc": "This is the status update text.",  // optional
                     "value": "This is an example update"  // optional
                 },
                 "profile_ids": {}, // don't define anything for this field, will be done only in doc.js
            }
    }

The doc.js file would then become:

    "create_update": {
            ...
            "params": {
                "text": {
                     "type": "string",
                     "desc": "Here you'd write the text for the status update.",
                     "value": "This is my status!"
                 },
                 "profile_ids": {
                     "type": "array",
                     "desc": "An array of profile id's that the status update should be sent to. Invalid profile_id's will be silently ignored.",
                     "value": ["4eb854340acb04e870000010", "4eb9276e0acb04bb81000067"]
                 },
            }
    }

With this change you no longer need to worry about the order of parameters. This also means that in the future, you could allow multi-language documentation to be generated by having multiple files (eg, doc_EN.js, doc_DE.js), with different people doing the writing and the programmers only caring about api.js.

If you'd like to keep these formats backwards-compatible, you can check whether params is an array or a hash (object), but personally, I'd suggest breaking backwards compatibility. It's a young project, it's too early to be burdened with backwards compatibility, and it's an easy change for people to do. :)

When I try to run make under OS X, I get these errors:

https://gist.github.com/finsterdexter/8244394

I assume I have something wonky with my setup, but since there are darwin_amd64 binaries, I'm also assuming this should work.

Instead of lists to make it more readable.

When something is wrong in doc.json

• missing class def
• missing param

I got some general error like:

template: php/readme.md:188:20: executing "php/readme.md" at <index $data.Doc $cla...>: error calling index: index of nil pointer

or

template: php/readme.md:170:6: executing "php/readme.md" at <index $data.Doc . "t...>: error calling index: index of nil pointer

Should we improve this error message? Like missing definition of class, or missing param def of method...

I get the following error:

invalid character '/' looking for beginning of object key string

I have my config files in the same folder as the alpaca binary and ran ./alpaca . --no-php --no-python --no-node.
Here are my config files: https://gist.github.com/manuelmeurer/0678cc19922ccabdfe46

Running v0.2.0 amd64 darwin on Mac OS X 10.9.1

Give the user an option to do this.

I am new to nodejs. Have you attempted to run the nodejs output through browserify (http://browserify.org/) and was it able to produce javascript that could be run in the browser?

Is there any plan to support Java?

PrntFunctionMaker should take care of it.

Hello,

Another format for API description that also can be used as source for code generation:
RESTful API Modeling Language (RAML)
http://raml.org/

RAML parser in Go:
https://github.com/go-raml/raml/

Go package that based on schema can generate RAML files and Go client:
https://github.com/alecthomas/rapid

Best regards,
Dobrosław Żybort

I'm sure I'm missing something. I read through the documentation and included the fields that are required. I'm getting the following error:

template: php/readme.md:171:20: executing "php/readme.md" at <index $data.Doc $cla...>: error calling index: index of nil pointer

Hello,

I would like to play with templates and I need to build alpaca on Windows but Makefile is a little cryptic to me.

Can you provide some simple step by step way of building alpaca on Windows (without compiling templates into it)?
Or maybe can you provide alpaca binary without templates compiled in?

Best regards,
Dobrosław Żybort

Sorry if this is not a bug, as this is my first exposure to namespaces (in PHP, anyway). The issue can be re-created using the generated Buffer PHP client code. To do so, please edit Client.php and instantiate the class as follows:

$x = new Client();

Then, run from command line with: php Client.php. This generates an error:

PHP Fatal error:  Class 'Buffer\HttpClient\HttpClient' not found ...

This issue was discovered when generating a new API client, which resulted in a similar error, the example is simply to help in reproducing (what appears to be) an issue.

PHP version used: 5.3.10.

Will keep reading up on namespaces and attempt to isolate the issue (or figure out the error on my end). Thanks.

Allow users to submit an -o option to assign an output directory

http://swagger.io

I was running the examples. All the examples except buffer give errors

invalid character '"' after object key:value pair
OR
invalid character '}' looking for beginning of object key string.

Some APIs return status of response in body. And some badly designed APIs return always HTTP 200 and real status code in body.

bit.ly: http://dev.bitly.com/formats.html

HTTP Response Status Code is 200 on all valid response in json and xml formats. In json and xml responses, the status_code and status_txt values indicate whether a request is well formed and valid.

• json { "status_code": 200, "status_txt": "OK", "data" : ... }
• json { "status_code": 403, "status_txt": "RATE_LIMIT_EXCEEDED", "data" : null }

ArangoDB: https://www.arangodb.org/manuals/current/HttpDatabase.html
Return codes

• HTTP 201 - is returned if the database was created successfully.
• HTTP 400 - is returned if the request parameters are invalid or if a database with the specified name already exists.
• HTTP 403 - is returned if the request was not executed in the _system database.
• HTTP 409 - is returned if a database with the specified name already exists.

{ "result" : true, "error" : false, "code" : 201 }

Would be nice if we could add code in body names to api.json.

I'm confused -- does this generate documentation with code examples, or does this generate source files that are examples for end users that can be compiled? I don't see any meanful examples of the end product.

I would like to create libraries for database ArangoDB (and at future for Wordpress) but it is self hosted and don't have one, static API URL.

Could you add method to generated libraries, so that programmers are forced to initialize API client with custom URL?
Like:

class Client(object):
    def __init__(self, base_url, auth={}, options={}):
        self.http_client = HttpClient(base_url, auth, options)

panic: interface conversion: interface is nil, not []interface {}

goroutine 1 [running]:
runtime.panic(0x1792a0, 0x210499380)
    /usr/local/lib/gvm/gos/go1.2/src/pkg/runtime/panic.c:266 +0xb6
github.com/pksunkara/alpaca/alpaca.ArrayInterfaceToString(0x0, 0x0, 0x1b5a50, 0x8, 0x201d40)
    /usr/local/lib/gvm/pkgsets/go1.2/global/src/github.com/pksunkara/alpaca/alpaca/utils.go:21 +0x43
github.com/pksunkara/alpaca/alpaca.ModifyData(0x21045e600)
    /usr/local/lib/gvm/pkgsets/go1.2/global/src/github.com/pksunkara/alpaca/alpaca/alpaca.go:54 +0x63
github.com/pksunkara/alpaca/alpaca.WriteLibraries(0x7fff5fbff817, 0x2, 0x210454841)
    /usr/local/lib/gvm/pkgsets/go1.2/global/src/github.com/pksunkara/alpaca/alpaca/alpaca.go:34 +0x7a
main.main()
    /usr/local/lib/gvm/pkgsets/go1.2/global/src/github.com/pksunkara/alpaca/main.go:48 +0x1ec

Installed the Darwin amd64 version of the packaged application

API

• Response.Formats.Default should exist if Response.Suffix exists.

DOC

Add an option to allow the user to do this.

Hi.
In case when api has many simple methods, which differ only one parameter, it could be useful to create multiple methods with that predefined parameter.

For example: DigitalOcean V2 API:
Droplet has many actions like: reboot, power on, power off. They differ only in parameter "type": "reboot", "power_on", "power_off".

Now I could to create method run_action($droplet_id, $type), but it's more easy to use simple methods like: reboot($id), power_on($id), power_off($id)

Best implementation (imho) could be something like this:

public function reboot($id, array $options = array())
{
    $body = (isset($options['body']) ? $options['body'] : array());
    $body['type'] = 'reboot';

    $response = $this->client->post('/droplets/'.rawurlencode($id).'/actions', $body, $options);

    return $response;
}

Regards

Library can decide to not allow the changing of base_url, api_version and user_agent

Hi there.

There is an error with generated result of method with url_use = true in php result.

Next api.json part

// ...
    "class": {
        "domain": {
            "retrieve": {
                "path": "/domains/:name",
                "method": "get",
                "params": [
                    {
                        "name": "name",
                        "required": true,
                        "url_use": true
                    }
                ]
            }
        }
// ...

generates

/**
 * domain retrieve desc
 *
 * '/domains/:name' GET
 *
 * @param $name domain retrieve name desc
 */
public function retrieve($name, array $options = array())
{
    $body = (isset($options['query']) ? $options['query'] : array());

    $response = $this->client->get('/domains/'.rawurlencode(name).'', $body, $options);

    return $response;
}

The problem is rawurlencode(name), it must be rawurlencode($name)

Regards

Reading from alpaca.yaml instead of alpaca.json

Hello,

would be nice to have option to use JSON Schema as API Source.

Heroku is using Ruby to generate API library in Go from they JSON Schema:
More info:
https://blog.heroku.com/archives/2014/1/9/auto_generating_a_go_api_client_for_heroku
https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api
Source code: https://github.com/bgentry/heroku-go

Best regards,
Dobrosław Żybort

"template: php/readme.md:159:16: executing "php/readme.md" at <index $data.Doc $cla...>: error calling index: index of nil pointer"

My API requires custom headers, for a use case similar to this scenario:

Where I've seen custom headers com up is in a system to system request operating on behalf of a user. The proxy system will validate the user and add "X-User: userid" to the headers and use the system credentials to hit the endpoint. The receiving system validates that the system credentials are authorized to act on behalf of the user, then validate that the user is authorized to perform the action. http://stackoverflow.com/a/9169270/149060

I was concerned that I didn't see support for them in the todo list.

Always generate methods in same (e.g. alphabetical) order.

Actual behaviour:
First time:

class Profile(object):

    def __init__(self, id, client):
        ...
    def reorder(self, order, options={}):
        ...
        return response

    def shuffle(self, options={}):
        ...
        return response

And second time it can output:

class Profile(object):

    def __init__(self, id, client):
        ...

    def shuffle(self, options={}):
        ...
        return response

    def reorder(self, order, options={}):
        ...
        return response

Big bug on the designer ( even in the officialdemo online ), Sheama and Options buttons on "Designer" tab are returning the following error :
View compilation failed - cannot find parent view: VIEW_BOOTSTRAP_EDIT_LIST for view: VIEW_alpaca....

http://apiblueprint.org

For tracking progress.

Although not all RESTful web services generate WADL files it would be nice to have a feature developed to generate client libs based on this document format.

A number of REST frameworks like Jersey support generation of WADL files.

Speaking of packagist and composer,
I found that it's easier to work on same directory with 2 branches:

• master: for php source itself which is generated from alpace
• alpace: hold JSON configuration

I then use a custom makefile to generate the API, copy to a temporary folder, the checkout to master branch, copy file back and commit.

I experiment with it for a bit https://github.com/kureikain/bandwidth-php (check out master and alpaca branch)

Though I feel it's tricky. Do you have any idea/method so I can work on same directory but maintain the API JSON file and the generate file at same time but keep them separate so when I published to registry, the API JSON file won't leak into PHP source.

This commit made the top-level keys in params documentation deterministic but not the lower levels.

Fantastic project, firstly.

I think it would benefit greatly from basic validations on parameters. For example, if you require an integer cost to be submitted in the request, the following would be added to the api.json

"purchase": {
    "args": ["id"],
    "list": {
        "path": "/purchases/"
    },
    "update": {
        "path": "/purchases/:id/",
        "method": "post",
        "params": [
            {
                "name": "cost",
                "validation": "integer",
                "required": true
            }
        ]
    }
}

This cuts down on requests that will automatically be rejected by the API anyway, and most libraries include them.