Add UUID parameter type

[vanDonselaar]

We're using UUID's rather than Integers in our API to identify entities. It would be nice to have a uuid parameter type rather than using string for UUID's.

[fededonna]

@vanDonselaar why not use a string with a regex and define your own type?

[vanDonselaar]

How can I 'define my own type' exactly? Sounds interesting!

When using the raml-for-jax-rs generator (or any other generator), the generator can decide to generate a java.util.UUID(or System.Guid in .NET) instead of a String which you'll have to cast to a UUID. After all, a UUID is a very well-defined type with a proper RFC. Regexes are nice, but by your reasoning we could also decide to remove the Integer type by replacing it with a string and a regex like ^[0-9]*$. 😉

[sichvoge]

Thats simple using the data type language introduced in RAML 1.0. For example:

types:
 UUID:
  type: string
  pattern: ^[0-9]*

[fededonna]

Yes, you can change integer for whatever you want, but that's not this case. You are trying to validate a string. you can define your type as follows

types:
  UUID:
    type: string
    pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

and please don't cast, try using something as tryParse, your code will look much nicer.

[vanDonselaar]

With 'cast' I actually meant doing UUID.fromString("my-uuid") in Java. Using a string and a regex is exactly what I'm already doing right now. And based on that experience, I came with this proposal. The point is that the code generators don't have any clue that a particular string with a regex is actually a UUID. For example, this is the code that is generated right now by raml-for-jax-rs:

public PostUuidExampleResponse postUuidExampleBySomeUuid(
        @PathParam("some_uuid")
        @Pattern(regexp = "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-(8|9|a|b)[a-f0-9]{3}-[a-f0-9]{12}$")
        @Valid
        String someUuid) throws Exception {
   UUID realUuid = UUID.fromString(someUuid);
   ...

The introduction of a UUID type would allow the generator to produce code like this:

public PostUuidExampleResponse postUuidExampleBySomeUuid(
        @PathParam("some_uuid")
        java.util.UUID someUuid) throws Exception {
    someUuid; // Correct type

[fededonna]

with the new typesystem code generators will need to know about types and you could also enrich that with raml annotations. I don't think UUID will be a great built in type to add to the typesystem.

[vanDonselaar]

Okay, sounds reasonable but that would imply that there is some kind of type registry where these types are all documented, right? So if I rephrase my question: how would a code generator know when to generate UUID's then? What are these annotations you're referring to? I don't see them in the 1.0 spec.

Slightly unrelated: I'm really curious why RAML, as an API definition language, also tries to be a definition language for models. There are already tons of formats and projects fully dedicated to model definition. We have JSON Schema, Apache Avro, XML Schema, Apache Thrift, Google Protobuf, etc. all having high quality model generators to nearly all programming languages. I'm wondering why RAML wants to re-invent this wheel rather than becoming the de facto API definition language and leave the models pluggable.

[fededonna]

Here you can check about annotation types.
https://github.com/raml-org/raml-spec/blob/raml-10/versions/raml-10/raml-10.md#declaring-annotation-types

As per API Definition RAML is only giving you more tools to define your types you are free to use it or not but you are not tied to it, you can also use xsd and json schema.

[vanDonselaar]

Thanks for the link.
And wrt to the types: choice is good so that's great. Let's make sure not to lose focus, because I really like RAML. 😉 Thank you for your time!

[fededonna]

No problem, we like users to be as free as they want while designing their APIs.