Skip to main content

Sylk Best Practices

  1. Use project templates: Sylk CLI offers several project templates that can be used to create a new project quickly. These templates come pre-configured with the necessary files and directory structure to get started with building your gRPC microservices.

  2. Split services into packages: Sylk encourages splitting your services into packages. This makes it easier to manage the codebase and reuse packages across different services. Use the package command to attach packages to your services.

  3. Use Sylk resources: Sylk CLI provides a set of resource types (e.g. message, enum, service) that can be used to define your service interfaces. Use these resources to keep your proto files organized and easy to read.

  4. Use Docker: Sylk CLI makes it easy to build your services as Docker containers. This is the recommended way to deploy your services to production.

  1. Version control: Use a version control system (e.g. Git) to manage your codebase. This makes it easier to collaborate with other developers and keep track of changes.

Following these best practices can help ensure that your Sylk project is well-organized, maintainable, and easy to work with.

Resource Oriented API's​

A resource-oriented API is generally modeled as a resource hierarchy, where each node is either a simple resource or a collection resource. For convenience, they are often called a resource and a collection, respectively.

The key characteristic of a resource-oriented API is that it emphasizes resources (data model) over the methods performed on the resources (functionality). A typical resource-oriented API exposes a large number of resources with a small number of methods. The methods can be either the standard methods or custom methods. For this guide, the standard methods are: List, Get, Create, Update, and Delete.

Sylk project built with resource-based APIs follows the same principles of organizing APIs as a resource hierarchy. Each node is either a resource or a collection, with a collection containing a list of resources of the same type. A resource has some state and zero or more sub-resources, which can be either a simple resource or a collection resource.

For example, a Sylk project for a messaging app could have a collection of users, with each user having a collection of messages, a collection of contacts, a profile resource, and several settings resources.

While a service with a resource-oriented API in Sylk may interact with storage systems, it is not necessarily a database and can have significant flexibility in interpreting resources and methods. For example, creating a new message (resource) may involve updating user status, sending notifications to the user's contacts, or triggering background processes for message indexing and analysis.

Naming Conventions​

In order to provide consistent developer experience across many APIs and over a long period of time, all names used by an API should be:

  • simple
  • intuitive
  • consistent

This includes names of interfaces, resources, collections, methods, and messages.

Since many developers are not native English speakers, one goal of these naming conventions is to ensure that the majority of developers can easily understand an API. It does this by encouraging the use of a simple, consistent, and small vocabulary when naming methods and resources.

  • Names used in APIs should be in correct American English. For example, license (instead of licence), color (instead of colour). Commonly accepted short forms or abbreviations of long words may be used for brevity. For example, API is preferred over Application Programming Interface.
  • Use intuitive, familiar terminology where possible. For example, when describing removing (and destroying) a resource, delete is preferred over erase.
  • Use the same name or term for the same concept, including for concepts shared across APIs.
  • Avoid name overloading. Use different names for different concepts.
  • Avoid overly general names that are ambiguous within the context of the API and the larger ecosystem of Google APIs. They can lead to misunderstanding of API concepts. Rather, choose specific names that accurately describe the API concept. This is particularly important for names that define first-order API elements, such as resources. There is no definitive list of names to avoid, as every name must be evaluated in the context of other names. Instance, info, and service are examples of names that have been problematic in the past. Names chosen should describe the API concept clearly (for example: instance of what?) and distinguish it from other relevant concepts (for example: does "alert" mean the rule, the signal, or the notification?).
  • Carefully consider use of names that may conflict with keywords in common programming languages. Such names may be used but will likely trigger additional scrutiny during API review. Use them judiciously and sparingly.

Using of Well-Known types​

Protocol Buffers are shipped with handy "Well-Knowns" messages that can be used in your sylk projects, here are some of them:

  • Timestamp: Will compile to Date objects
  • Empty: Is empty message just like void
  • Any: Can be used to have an aggregated endpoint of multiple and dynamic messages as any type of message can be packed and unpacked into Any message
  • Struct: Mimics a simple JSON structure with no pre-defined fields or no restrictions on values

It is prefered to use those well knowns and not written your own complex structure when there is no need. Sometimes those messages can spare you sometime of building your own schema.

Restrictions​

Sylk is built on top of Protocol Buffers and gRPC which make the building process of distributed systems easy and scalable but enforce the developer with some restrictions that MUST be followed.