Skip to content

Latest commit

 

History

History
152 lines (106 loc) · 6.38 KB

018-custom-id-support.md

File metadata and controls

152 lines (106 loc) · 6.38 KB

Custom ID Support

Summary

We are planning to support custom IDs to our resources like collections, documents, function tags and other resources. These will allow developers to provide pretty and understandable names to resources such as collections where IDs are required while making a query request.

Problem Statement (Step 1)

What problem are you trying to solve?

Developers want to name their resources with their own custom ID that they can easily query with. This will also help make query URL understandable and pretty.

What is the context or background in which this problem exists?

At the moment the IDs for all the resources are auto generated by Appwrite. Developers are forced to use the generated IDs in their applications to make queries. The generated ids are random and not easily understandable.

Once the proposal is implemented, how will the system change?

Every resource creation API will have an optional id attribute. Whenever id is not provided Appwrite will still generate the IDs as it is already doing. IDs will not be modifiable once the resource is created.

Design proposal (Step 2)

Resources that can have Custom IDs

  • Projects
  • Collections
  • Documents
  • Buckets
  • Files
  • Users
  • Function tags
  • Tasks
  • Webhooks
  • Functions
  • Teams
  • Memberships
  • Sessions
  • Executions
  • and more

Basically all the resources in Appwrite that has a Create endpoint and all future similar resources will support Custom ID.

The create resource endpoints for above resources will have a first required id parameter where users can send their custom id following the guidelines for validation. In every endpont, if the id parameter is received empty (required for backward compatibility with existing SDKs) or pre defined string, Appwrite will still generate the ids as it is already doing.

We can use the existing key validator to validate the custom id as well.

Some guidelines for custom ids

  • Can be at most 36 characters
  • Can be Alphanumeric
  • Can contain _ but not at the begining of the id
  • Cannot contain any other special characters
  • If ID already exists, it will throw an error

UI Changes

With support for Custom ID, certain services that already have Name becomes confusing and not so useful. So we suggest following changes.

Services that have names where we are depricating name field and use ID instead. Where ID will not be set to auto generate, but can choose to auto generate

  1. Project
  2. Platform
  3. Function
  4. Collection
  5. API Key
  6. Webhook
  7. Team

Services where we are deciding to set ID field to auto generate as default

  1. Users
  2. File
  3. Membership
  4. Execution

While deciding where to set auto generation by default, we have considered the volume of data that might be inserted as well as the importance and use cases of id. For example, Projects, platforms, Functions, etc, will be few in numbers and their IDs will be used extensively in APIs so are not set to auto generate by default. However, services like Users, File, Execution will be huge in numbers and IDs are not use extensively, are set to auto generate by default.

Prior art

Unresolved questions

SDKs

How to make SDKs look pretty when people don’t want custom id and want Appwrite to generate

  • We could pass predefined String "uid()" or "unique()" -> database.createCollection("uid()", "Avatars") or database.createCollection("unique()", "Avatars")
  • We could pass empty string -> database.createCollection("", "Movies")
  • We could create a separate class -> database.createCollection(new Uid(), "Movies") and if want to pass custom id it could be database.createCollection(new Uid("movies"), "Movies")

Backward Compabilities

Even though id will be a required parameter, existing SDKs and apps should work as they are without any issues generating custom ids. Having a default Value which allows generating the ID in the controllers should make this possible.

Future possibilities