At present, Apollo team only provides Java and .Net clients due to manpower constraints. For applications in other languages, you can directly obtain the configuration through the Http interface through the introduction of this article.

Also, if any team/individual is interested, they are welcome to help us to implement the client in other languages, please contact @nobodyiam and @lepdou for details.

Note: There are already clients for Go, Python, NodeJS, PHP, C++ contributed by enthusiastic users, for more information you can refer to Go, Python, NodeJS, PHP and other clients usage guide

1.1 Application access to Apollo

First you need to access your application in Apollo, you can refer to application access document for the specific steps.

1.2 Reading configuration from Apollo via Http interface with cache

This interface will fetch the configuration from the cache and is suitable for more frequent configuration pull requests, such as a simple polling of the configuration every 30 seconds.

Since the cache has a delay of at most one second, if you need to work with configuration push notifications to achieve real-time configuration updates, please refer to 1.3 Reading configuration from Apollo via Http interface without cache.

1.2.1 Http interface description

URL: {config_server_url}/configfiles/json/{appId}/{clusterName}/{namespaceName}?ip={clientIp}

Method: GET

Parameter Description.

1.2.2 Http interface return format

The Http interface returns JSON format, UTF-8 encoding, which contains all the configuration items in the corresponding namespace.

Return content Sample is as follows.

{
    "portal.elastic.document.type": "biz",
    "portal.elastic.cluster.name": "hermes-es-fws"
}

The configuration in the form of properties can be obtained via {config_server_url}/configfiles/{appId}/{clusterName}/{namespaceName}?ip={clientIp}

1.2.3 Testing

Since it is an Http interface, after the URL is assembled OK, it can be accessed directly through a browser, or a relevant http interface testing tool.

1.3 Reading configuration from Apollo via Http interface without cache

This interface will get the configuration directly from the database and can be used with configuration push notifications to achieve real-time configuration updates.

1.3.1 Http interface description

URL: {config_server_url}/configs/{appId}/{clusterName}/{namespaceName}?releaseKey={releaseKey}&ip={clientIp}

Method: GET

Parameter Description.

1.3.2 Http interface return format

This Http interface returns JSON format, UTF-8 encoding.

If the configuration has not changed (the incoming releaseKey and the server-side equal), HttpStatus 304 is returned, and the response body is empty.

If the configuration has changed, HttpStatus 200 is returned, and the response body is the meta information of the corresponding namespace and all configuration items in it.

The return content Sample is as follows.

{
  "appId": "100004458",
  "cluster": "default",
  "namespaceName": "application",
  "configurations": {
    "portal.elastic.document.type": "biz",
    "portal.elastic.cluster.name": "hermes-es-fws"
  },
  "releaseKey": "20170430092936-dee2d58e74515ff3"
}

1.3.3 Testing

Since it is an Http interface, after the URL is assembled OK, it can be accessed directly through a browser, or a relevant http interface testing tool.

1.4 Application-aware configuration updates

Apollo provides push notifications for configuration updates based on Http long polling, and third-party clients can decide whether they need to use this feature depending on their actual needs.

If you are not so sensitive to the configuration update time, you can sense the configuration update by refreshing it at regular intervals, the refresh frequency can be determined by the application itself, and it is recommended to be above 30 seconds.

If you need to be aware of configuration updates in real time (1 second), you can refer to the following document to implement the configuration update push feature.

1.4.1 Configuration update push idea

Here we suggest you to refer to Apollo’s Java implementation: RemoteConfigLongPollService.java, which has more than 200 lines of code and is relatively simple in general.

1.4.1.1 Initialization

The first thing we need to do is to determine which namespaces need to be configured for update pushing. Apollo’s implementation is to register a namespace when the program gets its configuration for the first time, so we know which namespaces need to be configured for update pushing.

The result of the initialization is a Map of notifications, the content is namespaceName -> notificationId (initial value of -1).

If you find any new namespace that needs to be configured for update pushing during the run, you can directly stuff it into the notification Map.

1.4.1.2 Request Service

Once you have the notifications Map, you can request services. Here we describe the logic of requesting services, please refer to the interface description later for specific URL parameters and descriptions.

1. request the remote service, bring your application information and notifications information
2. The server checks whether the notificationId is up-to-date for each namespace and corresponding notificationId passed to it.
3. if they are the latest, hold the request for 60 seconds, if there is no configuration change within 60 seconds, then return HttpStatus 304. if there is a configuration change within 60 seconds, then return the latest notificationId of the corresponding namespace, HttpStatus 200. If the notificationId is found to be older than the server, the latest notificationId of the corresponding namespace, HttpStatus 200, will be returned directly.
4. After the client gets the server side return, determine the return HttpStatus .
5. If the returned HttpStatus is 304, that the configuration has not changed, re-execute step 1.
6. If the returned HttpStauts is 200, the configuration has changed, for the change of namespace to pull configuration from the server again, see 1.3 Read configuration from Apollo through the Http interface without cache. Also update the notificationId in the notifications map. re-run step 1.

1.4.2 Http interface description

URL: {config_server_url}/notifications/v2?appId={appId}&cluster={clusterName}&notifications={notifications}

Method: GET

Parameter Description.

Note 1: Since the server side will hold the request for 60 seconds, please make sure that the timeout for the client to access the server side is greater than 60 seconds.

Note 2: Don’t forget to url encode for the parameters

1.4.3 Http interface return format

The Http interface returns a JSON format, UTF-8 encoding, containing the namespace with changes and the latest notificationId.

The return content Sample is as follows.

[
  {
    "namespaceName": "application",
    "notificationId": 101
  }
]

1.4.4 Testing

Since it is an Http interface, after the URL is assembled OK, it can be accessed directly through a browser, or a relevant http interface test tool.

1.5 Configuring access keys

Apollo has added an access key mechanism since version 1.6.0, so that only authenticated clients can access sensitive configurations. If the application has access keys enabled, the client needs to add a signature when sending a request, otherwise the configuration cannot be accessed.

Header information to be set.

1.6 Error Code Description

Under normal circumstances, the Http status code returned by the interface is 200, the following lists the non-200 error code descriptions that Apollo will return.

1.6.1 400 - Bad Request

The client needs to check whether the corresponding parameter is correct according to the prompt.

1.6.2 401 - Unauthorized

The client is not authorized, e.g. the server has configured the access key, but the client is not configured or configured incorrectly.

1.6.3 404 - Not Found

The resource to be accessed by the interface does not exist, usually the URL or the parameters of the URL are wrong, or the corresponding namespace has not yet been published for configuration.

1.6.4 405 - Method Not Allowed

The interface access method is incorrect, for example, the interface should use GET to use POST access, etc. The client needs to check whether the interface access method is correct.

1.6.5 500 - Internal Server Error

Other types of errors will return 500 by default. For this type of error, if the application cannot find the cause based on the prompt, you can try to check the server logs to troubleshoot the problem.