Skip to content

Latest commit

 

History

History
128 lines (86 loc) · 5.43 KB

client.adoc

File metadata and controls

128 lines (86 loc) · 5.43 KB

uDiscovery Client APIs

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under
the terms of the Apache License Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0
Table of Contents

1. Overview

In the following document we will elaborate on the design and requirements for the uDiscovery service client facing APIs.

Client APIs
sequenceDiagram

Client ->> UDiscoveryService: FindService()

Client ->> UDiscoveryService: FindServiceTopics()
Loading

In Client APIs above, Client represents the client-facing APIs to talk to uDiscovery database that can be found in the various language libraries such as up-cpp, up-java, etc.. that are used to find services and their topics.

2. Client Facing APIs

The client facing APIs of uDiscovery provide the means for uEs to discover services (where they are located, versions, etc…​), and topic metadata that a service produces (method id and permissions, publish topic message formats, etc…​). The API is declared in the udiscovery.proto.

Each uProtocol Language Library MUST implement the client-side APIs of udiscovery.proto using the uProtocol Communication Layer (uP-L2) API RpcClient.

2.1. FindServices()

The FindServices() API is used to find service instances matching search criteria like authority, instance ID and (major) version. The only mandatory part of the provided (search) URI is the uEntity ID (ue_id), the rest can be discovered. The recursive flag can be used to include the uDiscovery service instance’s parent nodes in the search.

  • MUST return a UCode.NOT_FOUND if no service matching the passed URI was found.

  • MUST return a UCode.INVALID_ARGUMENT if:

  • recursive==true and authority_name does not contain the wildcard *.

  • UUri is empty

  • MUST return a UCode.PERMISSION_DENIED if the caller is not permitted to query for that service.

2.1.1. Example Use Cases

Below are example string URIs that could be passed to the API.
Table 1. FindServices() Examples
URI recursive Description

up:/FFFF1234/FF/0

false

Find local instances & versions of service 1234.

up://*/FFFF1234/FF/0

false

Find instances & versions of service 1234 that are known to the local uDiscovery service instance.

up://*/FFFF0004/FF/0

true

Find instances & versions of service 4 that are known to the local uDiscovery service instance or any of its parent nodes.

up://*/11234/2/0

false

Find the authority_name for version 2 & instance 1 of service 1234.

2.2. GetServiceTopics()

The GetServiceTopics() API is used to fetch metadata about one or more topics (depending on what is passed in the UUri) so clients can know more metadata about the topic(s). Wildcard ue_id and/or resource_id can be used to fetch multiple UServiceTopic information. The UServiceTopic contains topic metadata such as the minimum permission level required to read from the topic, message name, payload format (how the message is encoded) and more.

  • MUST return a UCode.NOT_FOUND if no topic matching the URI was found.

  • MUST return a UCode.INVALID_ARGUMENT if the URI passed in is not a valid uProtocol UUri.

  • MUST return a UCode.PERMISSION_DENIED if the caller is not permitted to query for that topic.

2.2.1. Example Use Cases

Below are example use cases for the API when passed certain URIs (shown in string form) along with the expected results.

Table 2. GetServiceTopics() Examples
URI Description

up:/1234/2/8000

Return the UServiceTopic for topic 8000 of service 1234 version 2.

up:/1234/2/FFFF

Return repeated list of UServiceTopic for all tpoics from service 1234 version 2.
Note
 Please refer to the udiscovery.proto for details of the UDiscovery Client APIs.