Open ProLoser opened 8 years ago
@usarid et all: I am playing around with the api and was trying to leverage DataTypes. I noticed that the documentation here: http://apiworkbench.com/docs/ has a datatype of pet, and then another datatype of mammal and then another of a bird. Each one refers to the parent by it's type
property, which is a bit confusing (since we have types, datatypes, and just a plethora of type
-things).
What do you guys think about reusing the extends
syntax inside of datatypes to specify their parent types? I feel like if anywhere in the spec you would want to emulate OOP, it would be inside of the objects that most closely mirror OOP business objects and classes which extend one another.
A bird
datatype extends a mammal
datatype which extends a pet
datatype.
What do you guys think about changing usage
inside of libraries to description
? Since it's essentially a description, and to me it seems creating more variations or synonyms for similar concepts is unnecessary and creates a bigger API surface area and more specification people must memorize.
I agree that changing usage
to description
would make sense and is more descriptive; at least to me. Lets wait if more people have something to say here.
What do you guys think about reusing the extends syntax inside of datatypes to specify their parent types? I feel like if anywhere in the spec you would want to emulate OOP, it would be inside of the objects that most closely mirror OOP business objects and classes which extend one another.
I can't agree here. You actually define the behaviour to inherit properties by declare to be of a specific type when defining the type
of a data type. For me at least, that is much more convenient as using extends
. I don't think we should replicate what OOP did one by one and stick with simple mechanism to define data types w/o more boilerplate.
I realize it may be too-little, too-late or I may just not be knowledgable enough to speak on this subject, but I've just spent several hours poring over the 0.8 and 1.0 specs for RAML after starting a new job this week (never heard of RAML before) and have found a lot of the terminology used somewhat confusing and at the documentation can be quite self-referencing (making the barrier of entry ridiculously high).
I feel I'm finally starting to come around to understanding things, but I've just been wondering if you guys would be open to consider using a slightly more approachable terminology so that it's easier to adopt RAML.
If I am incorrect about any of my suggestions or understandings of RAML concepts in my proposals below, I would only submit that as evidence as the superfluous complexity of the syntax language
For instance:
Extensions
Why not use the OOP equivalent of
extending
orextends
instead of things likemasterRef
? You could call these BaseDefinitions (or BaseSchemas or structures or iunno).Overlays
Are these interfaces? Can't we just call these an interface? Or use an
implements
keyword?Traits
These are not that bad, but I'd probably throw around terms like
mixins
orpartials
? Iunno, I guess almost anything could be a partial.ResourceTypes
I mean, these feel like I'm either extending a resource type or mixing in a resource type? Do they really need to be a distinct object? Why can't you just reuse the terminology around extensions or includes or overlays and just provide some examples that says "Hey, you can put any block of raml into an
!include
able file that can then be merged with your own overriding inline raml, and here's a commonly used situation in which you would do so:[block of raml traditionally defining a resource type]
"Libraries
Why is an explicit type/object/abstraction even necessary for these? It just seems like a package, but we've got so many packages... I'd rather see us drop some of the types of packages. It seems superfluous when you could just provide some instructions to create a file like:
And just let people include that file ^ at the top level of their document?
The sheer variety of partials
I'm curious if it's even really necessary to build these explicitly distinct types. SecuritySchemes, Overlays, Extensions, Traits, Libraries, etc.
In a nutshell, you're just including sub-blocks of yaml or merging blocks of yaml together. Why do these even need to be explicitly defined in your docs? Why not simply allow including or merging anywhere?