REST granularity vs performance

Purpose

• Assess magnitude of issue
• Determine solution for list-type APIs that return more than just keys
• Approach has to work across various cases
• Consistent URI design to distinguish from existing key-only list APIs
• Consistent way to specify what additional attributes should be returned
• Limits to attributes or result count or both

Use Case - Home Page

Call Sequence:

Purpose	API	URI	Number of calls
Get all Tag Types	TagTypes GET	herd-app/rest/tagTypes	1
For each Tag Type, get Display Name	TagType GET	herd-app/rest/tagTypes/Tst_Ct	3
For each Tag Type, get root Tags	Tags GET	herd-app/rest/tags/tagTypes/MK	3
For each root Tag in each Tag Type, get Display Name	Tag GET	herd-app/rest/tags/tagTypes/MK/tagCodes/BMW	9
Total number of API calls			16

Performance Notes:

• Avg 500-800 ms for each request
• Last few requests had significant "stalled" time - they were waiting on browser due to limit of 6 active conns
• Total time 2.89s - but will scale poorly as # of categories increases

Outcomes

This is an issue that must be resolved for Shepherd Catalog. We must move beyond a world of list endpoints that return only keys and loops over single-entity get endpoints. This was okay (mostly) for a primarily programmatic user base where loops are easy and a few seconds really doesn't matter. UIs have different non-functional requirements and a few seconds is not cool at all. This will also simplify certain operations for programmatic consumers and decrease the number (if not complexity) of REST calls on the servers.

The approach to solve this is to create search endpoints for entities as required. These endpoints are distinguished from the "get all" list endpoints as follows:

• List endpoints return only keys - search endpoints return keys by default but users can optionally supply a list of fields
  • Optional list of fields is at this time limited to top-level elements in the response. If top-level element is complex, that entire section of response will be returned.
• List endpoints always return all results - search endpoints have optional filters to specify which results to return
• Search endpoints use SearchKey / Filter approach for AND-ing multiple entities and OR-ing multiple filters. This will not be supported initially but we will carry this in our interfaces starting now so we won't break anything to support this in the future.

The points above are consistent with the original BData Search approach and REST best practices.