Prototyping IDs: UUID, Base64, Base62?



I’m looking for recommendation on generating IDs while prototyping an API design.

There is number of options to choose from.
It seems, common choices are:

  1. ‘name’-kind (ubiquitous in almost every RESTful API/RAML tutorial I’ve seen e.g. book title, author full name, username)
  2. UUID
  3. Base-64
  4. Base-62 (e.g. Spotify API)
  5. IDs generated by data store (RDBMS or NoSQL databases (e.g. ObjectId in MongoDB))
  6. Base-58

Since design and prototyping phase should be quick, this aspect, to me, seems like a challenge, especially if I want to avoid too much of implementation details while working with RAML document(s).

How do you create IDs used in request/response examples in RAML way?



Typically I have seen two primary ways to do this. The first is to allow the DB to generate IDs, usually indexed IDs and you use those in sub resources {id} fields. The plus side is it is usually auto generated for you by the DB. One issue I have seen with this approach is any sort of data migration that may result in new IDs could screw up existing IDs still out in the field (e.g. clients that cache them, reference them, etc).

The other approach is that your DB would still use IDs for indexing, but you would generate a UUID in some fashion and use those generated IDs that always stay with the record regardless of any sort of data migration. I prefer this approach myself. It allows you to control the process of UUID generation for your specific needs and you can still build a mapping table of generated DB ids to your UUIDs if you prefer to manage them that way.


Thanks Kevin for your response.

The idea of using UUIDs sounds compelling indeed. At least it is under complete developer’s control.

Could you elaborate on how you generate IDs using DB for examples used in RAML spec?
If that is a case, or you simply use random IDs.

What is not entirely clear to me is do I need to keep the IDs consistent and well referenced within a RAML document in order to make mocked service and testing work well?

AFAIS, for example in Spotify api.raml, the IDs used in the examples (e.g. for queryParameters) are arbitrary and there seem to be no inter-referencing maintained (e.g. ID of a playlist that is updated is consistent with IDs of playlists collection).


We use a Java utility class to be honest. Works well enough. In representing them in RAML, as far as I have always done, I simply use the {id} in the resource path, and specify the id as string in the uriParameters. I dont know if I understand what you mean by keeping the IDs consistent and well references in the RAML file?


I mean if IDs in RAML file in examples should be consistent in any way.
For example, response example to /books/{title}/author should contain the same author ID as in example for /authors/{authorId}.

I do realise it might be unclear though :slight_smile:


I have just stumbled upon an interesting form of IDs in RAML examples.

The (and their IoTDataModels repository of .raml files) use a kind of dummy ID everywhere:

example: |
    "rt":     ["oic.r.body.weight"],
    "id":     "unique_example_id",
    "weight": 80,
    "weightunits":   "kg",
    "observedtime": "2016-02-15T09:19Z"

The "id": "unique_example_id" is a dummy ID used across all examples.