Simple, Comprehensive Tooling for Modern APIs.
apicollective / apibuilder Goto Github PK
View Code? Open in Web Editor NEWSimple, Comprehensive Tooling for Modern APIs
Home Page: https://www.apibuilder.io/
License: MIT License
Simple, Comprehensive Tooling for Modern APIs
Home Page: https://www.apibuilder.io/
License: MIT License
Simple, Comprehensive Tooling for Modern APIs.
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
It would be nice to have a Scala client which didn't have to run in the context of a Play application.
client.Api.instance.FailedResponse =>
quality.FailedResponse
we're back to a single field type for internal fields - and always a string. Just use a string so code will be simpler
http://www.apidoc.me/gilt/docs/shipping-calculator/latest
throws an error
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.
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.
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.
{ ... "required": "false" } => This is ignored as JSON parser treats asOpt[Boolean] => None
When the name space is specified in the JSON for a model it should be used as the package name for its case class.
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:
client.messages.sendMail(...)
rather than
client.messages.post(...)
>> 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
>> 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
webhook on commit to master and on creation of tag:
Eventually we might have users subscribed to a service and we can notify them (follow integration path of docker hub, for example)
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
rename parameters element to query
add a body element:
query
model
{ "fields": [] }
{ "type": "foo" }
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.
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.
currently logic is spread out in a few places - DRY UP
[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)
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"
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:
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
The current generated client only accepts a token (username) in the Client.authorize signature.
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.
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:
e.g.
trait Foo {
foo: String
}
case class FooImpl(foo: String) extends Foo
http://www.apidoc.me/gilt/docs/ionblaster/0.0.1-dev#model-version
for array, display type as [xxx] to match json
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.
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
It would be helpful if there was a type for email addresses. This could help prevent confusion in some situations.
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
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
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")
200: { type: "unit" }
maybe support
200: { }
which is more natural (unit doesn't exist in javascript)
api.json:
{
"schema": "0.0.1",
"base_uri": "http://www.example.com",
"models": { ... },
"resources": [ ... ]
}
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.
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.
When the server returns an error response code, the exception thrown by the ruby client does not show the response body.
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."
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"
}
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
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.
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.
options:
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.