ADR-43: Catalyst API and Protocol refinement

More details about this document
Latest published version:
GitHub decentraland/adr (pull requests, new issue, open issues)
Edit this documentation:
GitHub View commits View commits on


The Catalyst API has been evolving and adding different functionalities, endpoints and parameters as needed by the evolving platform requirements. Because of this needs, some changes while good decissions at the moment to unblock features, were not thought hollistically or now they may be causing too much unneded Data Transfer cost or have room for perfomance improvement for the Catalysts core processes like Bootstrapping and Synchronization.


After reviewing the Catalyst API we defined a set of changes to clean up and close a first version of the Catalyst Protocol. The changes that will be described below will enable us to:

List of API changes:

Deprecated endpoints won't be part of the Catalyst Protocol definition but we may keep some of them as internal troubleshooting tools, these endpoints will require a key in order to be used. Those endpoints that will be removed from the Protocol but remain available for internal use, have the SECURE tag in the change description.

Endpoints not mentioned in the following list will not suffer any change.

Endpoint Deprecate YES/NO Change Description
/content/deployments YES SECURE: This endpoint consumes DB resources inefficiently as it's equivalent to a SELECT ALL. This endpoint also has a complex UX with the application of many filters and a lot of parameters. We are going to tag this as TROUBLESHOOTING and add 2 new endpoints: one to retrieve the list of all pointers and another to retrieve the history of a given list of pointers. Catalyst synchronization will be done using /snapshots and /pointer-changes.
/content/pointers/{entityType} New endpoint Given an entity type (scene, wearables) this endpoint returns the list of all the pointers paginated
/content/pointers/{entityType}/history?pointer=0,0&pointer=1,1 New endpoint Given a list of pointers of the specified entity type, returns the history of deployments
/contents/{hashId}/active-entities NO SECURE: Change resource to /entities and include a parameter to expand it's functionality in order to be able to retrieve inactive entities
/content/failed-deployments YES SECURE: This endpoint should be removed from the public API, and only be used with a key for the Catalyst Monitor and for troubleshooting or the auto-fix deployments functionality
/lambdas/health NO We need to add more information like the Unhealthy message. Currently you get an unhealthy state and no information about why the service is unhealthy
/lambdas/contentv2/scenes YES Do we need the v2? this endpoint should be generic to retrieve the list of scenes of a given coordinates
/lambdas/contentv2/parcel_info YES The information provided by this endpoint is presnet in /content/entities/{entityType}?id={cid}. We are going to add some filters to the existing endpoint to help you select which part of the entity you want to retrieve, e.g. content, metadata
/lambdas/contentv2/contents/{cid} YES There are old entities v2 that are still requested and may still be valid. We need to see if we can update these entities and deprecate this endpoint
/lambdas/crypto/validate-signature YES SECURE: This should be done with a library in the client side. Add a new lambda to return the Graph URL that we are using or add this information to the /lambdas/contracts/servers endpoint
/comms/islands YES SECURE: Remove from the public API and add a key to use this information for troubleshooting
/comms/islands/{islandId} YES SECURE: Remove from the public API and add a key to use this information for troubleshooting
/comms/peers YES SECURE: Remove from the public API and add a key to use this information for troubleshooting


Rejected by DAO


/deployments: We are not aware if this endpoint is being used for anything else besides the Catalyst synchronization and bootstrapping processes.

The fetchAllDeployments method from the Catalyst Client will only be available to be used by the Catalyst Servers in order to sync all the Content Service history.

The rest of the changes should not cause any impact on the Catalyst clients


Copyright and related rights waived via CC0-1.0. Withdrawn