apicollective / apibuilder

Simple, Comprehensive Tooling for Modern APIs

apibuilder

Simple, Comprehensive Tooling for Modern APIs.

See https://www.apibuilder.io

apibuilder's Issues

Need to be able to interchange apidoc model (sub)schemas with Avro schemas

So that schema can be reused for Avro, or vice-versa, we need to support "double" types. Avro does not support "decimal" and apidoc does not support "double". Also, Avro requires "type" to be present for the actual schema, it would be nice to enforce that.

See the Avro schema specs at: http://avro.apache.org/docs/1.7.6/spec.html#schemas

Public vs. Private api's

I think it would be helpful to have the concept of public vs. private api definitions. Possibly with the addition of in-development apis. A public API is defined as an API where the endpoints are available on the web for anyone to use. A private API is one where the endpoints are on a private network. Some possible use cases:

• It would nice to put together an apidoc "tester" app, that would allow you to play with public API's through an app (ala what FB did here). We could do this generally, for all API's.
• Enable sorting/searching of API's by those with public endpoints. Would be kind of fun if you could search for API's that you could use.

Prevent namespace collisions in operation paths

Right now if someone were to declare operations with the following paths (and the same HTTP verbs) in api.json,
the scala methods generated would be identical:

/organizations/:organization/:name/teams
/organizations/:organization/:name/members

e.g.

    {
      "responses": {
        "200": {
          "type": "[team]"
        }
      },
      "description": "Retrieve the list of teams associated with the given organization.",
      "path": "/organizations/:name/teams",
      "method": "GET"
    },
    {
      "responses": {
        "200": {
          "type": "[team]"
        }
      },
      "description": "Retrieve the list of teams associated with the given organization.",
      "path": "/organizations/:name/members",
      "method": "GET"
    },

in api.json maps to

  /**
   * Retrieve the list of teams associated with the given organization.
   * @param name 
   */
  def getByName(
    name: java.lang.String
  )(implicit ec: scala.concurrent.ExecutionContext): scala.concurrent.Future[Any] = {
    val queryBuilder = List.newBuilder[(String, String)]


    GET(s"/organizations/${({ x: java.lang.String =>
      java.net.URLEncoder.encode(x, "UTF-8")
    })(name)}/teams", queryBuilder.result).map {
      case r if r.status == 200 => r.status -> r.json.as[List[Team]]
      case r => r
    }
  }

  /**
   * Retrieve the list of teams associated with the given organization.
   * @param name 
   */
  def getByName(
    name: java.lang.String
  )(implicit ec: scala.concurrent.ExecutionContext): scala.concurrent.Future[Any] = {
    val queryBuilder = List.newBuilder[(String, String)]


    GET(s"/organizations/${({ x: java.lang.String =>
      java.net.URLEncoder.encode(x, "UTF-8")
    })(name)}/members", queryBuilder.result).map {
      case r if r.status == 200 => r.status -> r.json.as[List[Team]]
      case r => r
    }
  }

in scala client.

Proposed solution (from val) is to add a function attribute to operation, like:
{
method: "POST",
path: "/organizations",
function: "createOrganization",
description: "Create a new organization."
}

When present, the name of the method would be inferred from here, instead of generated.

A test requires network (and shouldn't)

[error] Uncaught exception when running tests: java.net.ConnectException: Operation timed out
[trace] Stack trace suppressed: run last api/test:test for the full output.
Exception in thread "Thread-7" java.io.EOFException
at java.io.ObjectInputStream$BlockDataInputStream.peekByte(ObjectInputStream.java:2598)

API Version numbers should not be replaceable

In the UI it is possible to use the same version number for a json. This will later be used for things like the gem generation. I suggest that bugfix modifiers are applied to the version number when replacements occur. For example a version number 0.0.3 if it is replaced with a new json file then the version number should be required to be 0.0.3-1 where 1 increments if more replacements occur.

Generate traits for models and have the generated case classes extend them

e.g.

trait Foo {
foo: String
}

case class FooImpl(foo: String) extends Foo

Move Response class out of instance and into top level package

client.Api.instance.FailedResponse =>

quality.FailedResponse

Proper user login

Should not generate a UnitResponse wrapper error class

http://www.apidoc.me/gilt/code/svc-avro-schema-registry/svc-avro-schema-registry/play_2_3_client

{
method: "GET",
path: "/:subject/schemas/:fingerprint",
description: "Gets the schema with the specified fingerprint",
responses: {
200: {
type: "schema_details"
},
404: {
type: "unit"
}
}
},

We end up trying to create a class named:

case class UnitResponse(response: play.api.libs.ws.WSResponse) extends Exception {

  lazy val unit = response.json.as[Option[Unit]]

}

which is wrong

Named path parameters should infer types

if you have a model with an id:Long parameter, and you define an operation with a path, e.g.

GET /items/:id

id by default will be assumed to be a string given location in path. While you can specify a parameter and define the type that way, would be nice to infer the type from the model since we should know the model from the resource.

Generated client Basic Auth requires ability to accept password for username:password scheme

The current generated client only accepts a token (username) in the Client.authorize signature.

Document body parameter in operations

http://www.apidoc.me/gilt/docs/gilt-dw-events/0.0.49#model-credit-card

Operations that accept bodies do not have their bodies listed in the online documentation

Support different versions of api.json

api.json:
{
"schema": "0.0.1",
"base_uri": "http://www.example.com",
"models": { ... },
"resources": [ ... ]
}

Support for enums

Markdown (or whatever) in descriptions

It would be awesome if we had some simple formatting for descriptions in situations where need to list something or do something funny. See this example:

{
"name":"type",
"type":"integer",
"description":"0 - tram/lightrail, 1 - subway, 2 - rail, 3 - bus, 4 - ferry, 5 - cable car, 6 - gondola, 7 - funicular"
}

Organization domains

setup organization domain lists... e.g. Gilt can list gilt.com and giltcity.com - users that register with this domain should get a verification email. Once email is verified, they are automatically added to the organization.

Shorthands for date and money

I think it would be cool if shorthands for very specific types like date-time-iso8601 were offered. No one wants to type the whole thing. I don't think it's confusing to establish that the default date format is iso-8601. Other formats would need to be explicitly specified. It's disruptive when I need to alt-tab to c/p the type.

Unique client identifier feature request

Currently there is no way to tell which client a request has come from as you would have to include it in all the parameter lists.
--The generated routes should be changed to include a * which would be the client id.
--The generated clients should have a unique value inserted upon download.

This will allow for tracking client based issues.

Ruby Client swallows response body when an error occurrs

When the server returns an error response code, the exception thrown by the ruby client does not show the response body.

[RubyClient] Models without resources have broken methods

See generated client here: https://gist.github.com/jenglert/3539880a906da1cd1357

The method email_addresses references a EmailAddresses which doesn't exist.

 >>client.email_addresses
NameError: uninitialized constant TransactionalEmailDeliveryService::Clients::EmailAddresses
    from /web/gilt/vendor/bundler_gems/ruby/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:440:in `load_missing_constant'
    from /web/gilt/vendor/bundler_gems/ruby/1.8/gems/activesupport-2.3.2/lib/active_support/dependencies.rb:80:in `const_missing'
    from (irb):37:in `email_addresses'
    from (irb):480
    from :0

Remove InternalFieldType

we're back to a single field type for internal fields - and always a string. Just use a string so code will be simpler

Bug parsing booleans as strings

{ ... "required": "false" } => This is ignored as JSON parser treats asOpt[Boolean] => None

Move imports to top of generated client

parameters - query + body

rename parameters element to query
add a body element:
query
model
{ "fields": [] }
{ "type": "foo" }

Cleanup implementation and validation of codegen targets

currently logic is spread out in a few places - DRY UP

Remove money type- we are just using big decimal now

Error accessing apidoc

http://www.apidoc.me/gilt/docs/shipping-calculator/latest

throws an error

App shows generic play error page when uploading bad api.json

Gives no information about what is wrong with the file.

Enums as first class objects

I have an api where I reuse an enum in a few places. Currently, reuse involves repeating specification in the apidoc.

Additionally, I would like to be able to give my enums descriptions, such as examples for when they would be used. Currently, I would have to shove all this in the description element of the field, which becomes problematic when updating an enum used in multiple places.

Remove multi valued column from online docs

http://www.apidoc.me/gilt/docs/ionblaster/0.0.1-dev#model-version

for array, display type as [xxx] to match json

Support documentation of custom headers

example:

val awsAccessKeyId = request.headers.get("X-AWS_ACCESS_KEY_ID")
val awsSecretAccessKey = request.headers.get("X-AWS_SECRET_ACCESS_KEY")
val awsRegion = request.headers.get("X-AWS_REGION")

Should we support specifying query parameters as objects?

shipping calculator has this:

    "ship_quote": {
        "path": "/ship_rates/quote",
        "operations": [
            {
                "method": "GET",
                "description": "Get a shipping quote for the given list of items, shipping to the given destination.",
                "parameters": [
                    { "name": "items", "type": "[item]" },
                    { "name": "destination", "type": "string", "description": "The region to which the items are shipping. It is assumed that a quote is requested for a single order." }
                ],
                "response": "[ship_quote]"
            }
        ]
    }

We currently are throwing an error that we do not know how to turn the array of Item instances into query parameters.

ruby method names in client aren't quite right

http://www.apidoc.me/gilt/code/jira-rest-client/0.0.1-dev/ruby_client

def expandedProjects
@expandedProjects ||= JIRARestClient::Clients::ExpandedProjects.new(self)
end

def groupss
  @groupss ||= JIRARestClient::Clients::Groupss.new(self)
end

Ruby client truncates url after first slash

The generated ruby client uses the URI.parse method to initialize the "@url" variable in the Module::Client.new("url") truncates the URL when the "+" method is used to append urls to anything other than the base domain.

This works: Module::Client.new("https://www.apidoc.me")

This won't: Module::Client.new("https://jira.gilt.com/rest/api/latest/"). The base url is replaced with "https://jira.gilt.com/projects/path"

organization should be included in api.json / generated code

Currently we generate code with package names like svcavroschemaregistry.models. This has the potential for conflicts between multiple organizations, and also just seems like poor practice. I think it would be better if we included the com.gilt organization in the package.

"unit" type is unnecessary in api.json

200: { type: "unit" }

maybe support

200: { }

which is more natural (unit doesn't exist in javascript)

how to use it ?

Hi,I found this on your play all days video.but I really can not found how to get start,like how to use it in my play project.
could you update the README or point me where to get start?
thanks

client side tool to validate json

Would be great to have a simple client side tool that validated your json

In API: expose an endpoint that does not require validation that accepts an api.json file and returns a validation message or maybe just a list of validation errors.

Having no errors would be a sign that the json validated.

Then we could provide a wrapper (go client?) that provided a nice CLI, e.g:

apidoc validate api.json
=> Your document is valid

apidoc validate api.json
=> Your document is invalid:

• "foo" is not a valid type

Model's package name should be pulled from the model's namespace in the JSON

When the name space is specified in the JSON for a model it should be used as the package name for its case class.

Github integration

webhook on commit to master and on creation of tag:

• fetch api.json from github
• update the api

Eventually we might have users subscribed to a service and we can notify them (follow integration path of docker hub, for example)

Play 2 Routes should use UUIDs

Write now any query parameter specified as a uuid in api.json will produce a String in the play routes file, instead of a UUID. Play fully supports UUIDs as query parameters, so it would be preferable to use UUIDs.

Stand-alone scala clients

It would be nice to have a Scala client which didn't have to run in the context of a Play application.

Support for generic objects (maps)

curl -i -u xxx: -X POST -H "Content-Type: application/json" -d '{ "name": "heartbeat", "tags": { "service": "svc-sku-pricing", "host": "svc12.prod.iad" }, "timestamp": 1403616720, "value": 1 }' http://api.cavellc.io/organizations/gilt/teams/architecture/metrics

In this case tags is an object of Map(String -> String) which would be nice to support

Add link to avro schemas

Ruby Client Hard to Follow

TBH, I found the ruby client very hard to follow. (For reference, I was using the client generated by transactional email service https://gist.github.com/jenglert/3539880a906da1cd1357). Basically, we need to make it easier to figure out how to use the thing. Some suggestions:

• It would greatly aid readability if the actual bits you might call were at the top of the file.
• Classes that are repeated in every client should be at the bottom, and hopefully below a comment indicating that stuff below the comment isn't client specific (and can be ignored by people looking for the interface).
• The models module should come after the clients module
• My method to send email was named 'post'. This isn't really great in my opinion. The method should be named sendMail IMO. Consider someone reading an application of the client. It would be much easier to parse

client.messages.sendMail(...)

rather than

client.messages.post(...)

• The method post accepted a hash instead of a list of parameters. This makes it hard to know which information you need to pass in the Hash to get an email to send. It also makes it hard to type check anything other than the fact that I supplied a hash. For example, the following should have provided a more concrete error message:

>> client.messages.post({})
TransactionalEmailDeliveryService::HttpClient::ServerError: TransactionalEmailDeliveryService::HttpClient::ServerError
    from (irb):235:in `http_request'
    from (irb):204:in `do_request'
    from (irb):158:in `post'
    from (irb):81:in `post'
    from (irb):467
    from :0

• Error messages are fairly undecipherable. For example, I have no idea why this is failing. I think we should consider error messaging a first class product of the client.

>> client.messages.post({"idempotent_token"=>"test", "subject"=>"hi", "body"=>"body", "to"=>"[email protected]", "account"=> "gilt", "email_description"=>"jimtest", "priority"=>1})
TransactionalEmailDeliveryService::HttpClient::ServerError: TransactionalEmailDeliveryService::HttpClient::ServerError
    from (irb):235:in `http_request'
    from (irb):204:in `do_request'
    from (irb):158:in `post'
    from (irb):81:in `post'
    from (irb):477
    from :0

docs say enum choices are specified with field "values", but really it's "enum"

http://www.apidoc.me/doc/apiJson

"values Json Array of String values. This option can be used to define an enumeration - values provides the list of all of the acceptable values for this field. There are a few constraints on enumerations. First, the datatype must be string. Second, the values themselves must be proper names. Valid characters are a-z, A-Z, 0-9 and _ characters."

Email type

It would be helpful if there was a type for email addresses. This could help prevent confusion in some situations.

Link to apidoc in descriptions

For example: I have the following model:

"purchase_order_line_item" : { 
  "description": "Line level receiving information for a [purchase_order]",
  "fields": [
    { "name": "lineNumber", "type": "long" },
    { "name": "skuId", "type": "long" },
    { "name": "quantity", "type": "long" }
  ]   
},  

I would like apidoc to automatically generate a link to the purchase_order model, similar to how a "type" field with a model would.

Update docker file to build app in containers

resources and models

options:

1. make models an array to be same as resources
2. put operations back into the models
3. make resources a map
4. rename "resources" to "operations" and make it a map