4 ms·

It looks like Teleport is trying to do too many things. Input validation systems are great - there's an excellent one for Python already, called Schematics (ht

It looks like Teleport is trying to do too many things. Input validation systems are great - there's an excellent one for Python already, called Schematics (https://github.com/schematics/schematics https://github.com/schematics/schematics). Declarative schema systems are also great - JSON Schema (http://json-schema.org/ http://json-schema.org/) is the industry standard for JSON. The clever thing about JSON Schema is that it is itself written using JSON - so it's completely language independent. A JSON Schema is a document which you can a) version and b) upload to a schema repository like Iglu (https://github.com/snowplow/iglu https://github.com/snowplow/iglu). I don't see any equivalent non-language-tied schema approach in Teleport. Thirdly, tooling to help document APIs is also a great aim - the go-to project here is Swagger (https://helloreverb.com/developers/swagger https://helloreverb.com/developers/swagger). These are all huge problems _in themselves_, and the above solutions have lots of cross-platform tooling, developer mindshare and polyglot language support. I think you need to decide what problem you want Teleport to solve...

fiatjaf 12y ago
Don't listen to this. Do your thing. Industry standards also die and change.
- boronine 12y ago
  Thank you!
curun1r 12y ago
Swagger may claim to be polyglot, but it seems really Java focused to me and I've yet to see an implementation for another language, particularly one that's difficult to analyze statically (the power of swagger is the ability to generate the majority of the API documentation from code and annotations, something not possible in dynamic languages), that's not a huge train wreck. Solutions like http://apiblueprint.org/ http://apiblueprint.org/ and http://raml.org/ http://raml.org/ are much more language-neutral than Swagger.
- alexatkeplar 12y ago
  Ruby support for Swagger: https://github.com/richhollis/swagger-docs https://github.com/richhollis/swagger-docs https://github.com/tim-vandecasteele/grape-swagger https://github.com/tim-vandecasteele/grape-swagger JS support for Swagger: https://github.com/wordnik/swagger-node-express https://github.com/wordnik/swagger-node-express https://github.com/wordnik/swagger-js https://github.com/wordnik/swagger-js PHP support for Swagger: https://github.com/zircote/swagger-php https://github.com/zircote/swagger-php Etc. Sure Swagger is fairly opinionated about what a RESTful API should look like, but claiming it's Java-focused is off the mark.
  - curun1r 12y ago
    I don't use Ruby or PHP, but the JS support is laughable. Getting it to even work is a challenge (the code is pretty terrible) and the code they force you to write is ugly, overcomplicated and unlike an idiomatic node API code. The Python support is somewhat better, owing to Python's annotations. But there are languages like C++ and Rust that are completely unsupported. But you can't be language-independent if you require specific languages features that aren't present in all languages and require specific language integrations that need to be written for every language. Options like the two that I mentioned before are actually language-independent.
    - alexatkeplar 12y ago
      Interesting, I'll take another look at RAML. I have to confess I found it a bit weird that when we started with Swagger that we couldn't start "schema first" (i.e. just describe the API in a doc, but instead had to start with the annotations). I guess that's part of the wider problem you describe.
zachrose 12y ago
I actually see these concerns to be so close together that you might as well do them all at once. In fact, jayschema, the JSON schema library I've been useing lately, comes very close to having user-readable validation errors. Also, looking at a JSON schema with appropriate description fields is about as good as some API docs. (Sure, API docs sometimes need to tell you more than just data structures, but isn't there a quote about good data structures making the program seem obvious?) If anything, I'm interested in knowing if Teleport schemes can be mapped to JSON schemes and vice-versa.
- alexatkeplar 12y ago
  Actually, you're right. JSON Schema is very effective as an input validation mechanism (we use it for this at Snowplow), and if you look at Swagger, it actually uses JSON Schema-based types for modelling the entities exposed by a RESTful API. I am a huge fan of JSON Schema - I don't yet see what Teleport is bringing to the table.

fiatjaf 12y ago

Don't listen to this. Do your thing. Industry standards also die and change.

boronine 12y ago
Thank you!

curun1r 12y ago

Swagger may claim to be polyglot, but it seems really Java focused to me and I've yet to see an implementation for another language, particularly one that's difficult to analyze statically (the power of swagger is the ability to generate the majority of the API documentation from code and annotations, something not possible in dynamic languages), that's not a huge train wreck. Solutions like http://apiblueprint.org/ http://apiblueprint.org/ and http://raml.org/ http://raml.org/ are much more language-neutral than Swagger.

alexatkeplar 12y ago
Ruby support for Swagger: https://github.com/richhollis/swagger-docs https://github.com/richhollis/swagger-docs https://github.com/tim-vandecasteele/grape-swagger https://github.com/tim-vandecasteele/grape-swagger JS support for Swagger: https://github.com/wordnik/swagger-node-express https://github.com/wordnik/swagger-node-express https://github.com/wordnik/swagger-js https://github.com/wordnik/swagger-js PHP support for Swagger: https://github.com/zircote/swagger-php https://github.com/zircote/swagger-php Etc. Sure Swagger is fairly opinionated about what a RESTful API should look like, but claiming it's Java-focused is off the mark.
- curun1r 12y ago
  I don't use Ruby or PHP, but the JS support is laughable. Getting it to even work is a challenge (the code is pretty terrible) and the code they force you to write is ugly, overcomplicated and unlike an idiomatic node API code. The Python support is somewhat better, owing to Python's annotations. But there are languages like C++ and Rust that are completely unsupported. But you can't be language-independent if you require specific languages features that aren't present in all languages and require specific language integrations that need to be written for every language. Options like the two that I mentioned before are actually language-independent.
  - alexatkeplar 12y ago
    Interesting, I'll take another look at RAML. I have to confess I found it a bit weird that when we started with Swagger that we couldn't start "schema first" (i.e. just describe the API in a doc, but instead had to start with the annotations). I guess that's part of the wider problem you describe.

zachrose 12y ago

I actually see these concerns to be so close together that you might as well do them all at once. In fact, jayschema, the JSON schema library I've been useing lately, comes very close to having user-readable validation errors. Also, looking at a JSON schema with appropriate description fields is about as good as some API docs. (Sure, API docs sometimes need to tell you more than just data structures, but isn't there a quote about good data structures making the program seem obvious?) If anything, I'm interested in knowing if Teleport schemes can be mapped to JSON schemes and vice-versa.

alexatkeplar 12y ago
Actually, you're right. JSON Schema is very effective as an input validation mechanism (we use it for this at Snowplow), and if you look at Swagger, it actually uses JSON Schema-based types for modelling the entities exposed by a RESTful API. I am a huge fan of JSON Schema - I don't yet see what Teleport is bringing to the table.