Client Apps
Managing APIs via Client Apps.
As discussed the Concepts section, Client Apps represents the software runtime that implements specific business function using a set of APIs.
The goal of Client Apps is to provide a simple way to manage the set of APIs used by your software.
The set of APIs used by the Client App is called Scope of the Client App.
Creating a Client App
Installing APIs
API can be installed (added) to the Client App by adding the API name to the API Access list.
When adding an API to the scope of the Client App, you need to specify what is the Client App allowed to do with this API by specifying a list of permissions.
Permissions are represented by a list of strings.
It is up to the API provider how to interpret the permissions. You need to check the documentation of the API to see what permissions are supported and what methods are going to be accessible with specific permissions list.
myAPIz defines a set of standard permissions based on POSIX file permissions
- read - read access to the API resource, e.g. read or list a resource
- write - write access to the API resource, e.g. modify, create, delete a resource
- execute - execute access to the API resource, e.g. execute, evaluate a resource or a function
With this simplified permissions model, we are looking for a familiar and simple way to cover most of the authorization use-cases needed by APIs.
It is up to the API provider to utilize the permissions model and define the set of permissions that are applicable to the API.
Authentication
Key-based Authentication
Key-based authentication is the simplest way to authenticate with myAPIz. It is highly recommended for server-based communication and in limited cases for client-server communication.
To use key-based authentication, you need to use a valid key generated and assigned to your Client App. It is possible to have multiple keys in order to transition to new key in cases of key expirations.
When Client App need higher level of security, it is recommended to use another authentication mechanism, setup in another Client App.
Best Practices
Naming
Name the Client Apps after the names of the service, runtime, application as known in your organization. In some cases, where one application needs multiple client apps for security reasons, you can use suffixes in the name denoting the purpose of the client App.
E.g. ClientPlatform, and ClientPlatform-Deployment clients corresponding to the production web application and the deployment script that needs to publish some resources to the APIs.
Keep the names concise and meaningful while adding more details in the description field.
Scope and Permissions
Following the principle of least privilege, it is recommended to limit the scope and permissions of the Client App to the APIs that are actually needed by the Client App.
For module-based applications, it is recommended to create a Client App per module and limit the scope of the Client App to the APIs that are actually needed by the module.
Credentials
It is recommended to use a key-based authentication for server-based Client Apps and to rotate the keys periodically.
Credentials need to be handled with care and we recommend the following practices: