Skip to content
AEP

Unreachable resources

Occasionally, a user may ask for a list of resources, and some set of resources in the list are temporarily unavailable. For example, a user may ask to list resources across multiple parent locations, but one of those locations is temporarily unreachable. In this situation, it is still desirable to provide the user with all the available resources, while indicating that something is missing.

Guidance

If a method to retrieve data is capable of partially failing due to one or more resources being temporarily unreachable, the response message must include a field to indicate this:

message ListBooksResponse {
  // The books matching the request.
  repeated Book books = 1;


  // The next page token, if there are more books matching the
  // request.
  string next_page_token = 2;


  // Unreachable resources.
  repeated string unreachable = 3;
}
  • The field must be a repeated string/string array, and must be named unreachable.
  • The field must be set to the paths of the resources which are the cause of the issue, such as the parent or individual resources that could not be reached. The objects listed as unreachable may be parents (or higher ancestors) rather than the individual resources being requested. For example, if a location is unreachable, the location is listed.
    • The response must not provide any other information about the issue, such as error details or codes. Toe enable users to discover what the underlying issue is, APIs should provide an API method that provides more specific information.
    • The service must provide a way for the user to get an error with additional information, and should allow the user to repeat the original call with more restrictive parameters in order to do so.
    • The resource paths provided in this field may be heterogeneous. The field should document what potential resources may be provided in this field, and note that it might expand later.

Pagination

When paginating over a list, it is likely that the service will not know that there are unreachable parents or resources initially. Further, parents may alternate between being available and unavailable in unpredictable ways throughout the process of listing all the requested resources.

These facts lead to the following guidance:

  • The response must provide any outstanding unreachable locations or resources in the unreachable field on pages following the final page that contains a resource.
    • The response should not include both requested data and unreachable resources on the same page.
      • For example, if there are two pages of books and one unavailable publisher, there should be three pages total: first the two pages of books, and then a final page with no books and the unavailable publisher.
    • If the number of unreachable resources to list is very large, the response should honor the max_page_size field in the same way as for resources. In this case, all pages with requested information should precede all pages with unavailable resources or locations.
    • The final page’s unreachable field must only include resources or parents that were partially provided (or missing completely) across the entirety of the pagination process.
      • For example, if a parent or resource was unreachable at the beginning of pagination and it became reachable again and the entire set of previously unreachable data was provided to the user on any page, the unreachable field must not include the intermittently-unreachable parent or resource.
      • On the other hand, if only some of the resources for a given parent are provided during such an incident as described above, the parent or resource must be included in the unreachable field.

Further reading