34 lines
1.9 KiB
Markdown
34 lines
1.9 KiB
Markdown
# Clients
|
|||
|
|
|
||
|
|
Clients are Go packages that provide easy access to application's API or external API. Hence, this document describes two types of clients:
|
||
|
|
|
||
|
|
- **Own client**.
|
||
|
|
- **External API client**.
|
||
|
|
|
||
|
|
## Own client
|
||
|
|
|
||
|
|
Own client is a client to application's own network API that is accessible through domain's deliveries (see [Deliveries](deliveries.md)). It should conform to this set of rules:
|
||
|
|
|
||
|
|
- Be placed in `client` package in project's root directory.
|
||
|
|
- Be configurable with functional options.
|
||
|
|
- NOT expose low-level API (e.g. ability to configure HTTP client by assigning parameters directly to its fields).
|
||
|
|
- Have `schema` package in it with API contract's data schema.
|
||
|
|
- Have proper and comprehensive comments on exported functions, structures and their fields.
|
||
|
|
- Public (exported) functions should return schema structure and error or just error if no data is returned.
|
||
|
|
- Validate request's data before launching network communication.
|
||
|
|
|
||
|
|
Own client should be explicitly mentioned in ADRs (Architecture Decision Records) or any other document that describes application's functionality. If own client isn't mentioned there - it should not be implemented.
|
||
|
|
|
||
|
|
Also, own client should not receive `*application.Application` as it won't be on end-user side. For lifecycle-related things it should receive `context.Context` via configuration.
|
||
|
|
|
||
|
|
### API contract schema
|
||
|
|
|
||
|
|
All data that goes via own client should be wrapped in a structure that lies in `schema` package within client for extensibility and maintainability.
|
||
|
|
|
||
|
|
Every schema structure should have `Validate() error` function that validates request's data early, before it goes to API.
|
||
|
|
|
||
|
|
## External API client
|
||
|
|
|
||
|
|
External API client is a client to externally hosted application. It should conform to the same rules as own client with these exceptions:
|
||
|
|
|
||
|
|
- Client should be placed in `client` directory of domain (see [Domains](domains.md)) and should not be within "core" or "features" domains.
|