diff --git a/docs/apis/_index.md b/docs/apis/_index.md index f482531a7a..f30eff878c 100644 --- a/docs/apis/_index.md +++ b/docs/apis/_index.md @@ -6,4 +6,48 @@ geekdocFilePath: _index.md geekdocCollapseSection: true --- +{{< toc-tree >}} + Infinite Scale provides a large set of different **application programming interfaces (APIs)**. Infinite Scale is built by microservices. That means many calls to "functions" in the code are remote calls. + +Basically we have two different API "universes": [HTTP](http) and [gRPC](grpc_apis). + +{{< columns >}} + +{{< figure src="/ocis/static/http-logo.png" width="70%" alt="Image sourced from https://commons.wikimedia.org/ free of licenses" >}} +<---> + +{{< figure src="/ocis/static/grpc-logo.png" width="70%" alt="Image sourced from https://grpc.io/ under CC 4.0 BY license" >}} + +{{< /columns >}} + + +For inter-service-communication we are using mostly gRPC calls because it has some advantages. In the future, clients may decide to use gRPC directly to make use of these advantages. + +{{< figure src="/ocis/static/ocis-apis.drawio.svg" class="page-image">}} + +## [HTTP](http) + +HTTP APIs are mostly used for client <-> server communication. Modern applications are embracing a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) software architecture style. REST APIs are using the HTTP protocol to transfer data between clients and servers. All our clients talk to the Server using HTTP APIs. This has legacy reasons and is well-supported across many platforms and technologies. Infinite Scale uses an [HTTP API gateway](../services/proxy) to route client requests to the correct service. + +### OpenAPI + +It is best practise to define APIs and their behavior by a spec. We are using the OpenAPI standard for all new APIs. The [OpenAPI Specification](https://swagger.io/specification/), previously known as the Swagger Specification, is a specification for a machine-readable interface definition language for describing, producing, consuming and visualizing RESTful web services. Previously part of the Swagger framework, it became a separate project in 2016, overseen by the OpenAPI Initiative, an open-source collaboration project of the Linux Foundation. Swagger and some other tools can generate code, documentation and test cases from interface files. + +### RFC + +Some APIs have become a de facto standard and are additionally covered by an [RFC](https://en.wikipedia.org/wiki/Request_for_Comments). + +## [gRPC](grpc_apis) + +In gRPC, a client application can directly call methods on a server application on a different machine as if it was a local object. This makes it easier to create distributed applications based on microservices. In gRPC we can define a service and specify the methods that can be called remotely. A gRPC client has a stub that provides the same methods and types as the server. +Infinite Scale uses a [gRPC API Gateway](../services/gateway) to route the requests to the correct service. + +### Protobuf + +gRPC APIs are typically defined by [Protocol buffers](https://developers.google.com/protocol-buffers/docs/overview). The different client and server stubs are created from ``*.proto`` files by code generation tools. + +## Versioning + +There are different standards for API versioning: Through URL, through request parameter, through custom header and through content negotiation. Ocis uses the versioning by URL concept although this creates a big code footprint. The versioning follows [SemVer](https://semver.org). We update the major version number when breaking changes are needed. Clients can decide which major version they use through the request URL. The specific implementation is documented on each API. + diff --git a/docs/apis/grpc_apis/_index.md b/docs/apis/grpc_apis/_index.md index 3dd2acefd3..78ea417719 100644 --- a/docs/apis/grpc_apis/_index.md +++ b/docs/apis/grpc_apis/_index.md @@ -6,6 +6,58 @@ geekdocFilePath: _index.md geekdocCollapseSection: true --- +{{< toc-tree >}} + ## **R**emote   **P**rocedure   **C**alls [gRPC](https://grpc.io) is a modern open source high performance Remote Procedure Call (RPC) framework that can run in any environment. It can efficiently connect services in and across data centers with pluggable support for load balancing, tracing, health checking and authentication. It is also applicable in last mile of distributed computing to connect devices, mobile applications and browsers to backend services. + +## Advantages of gRPC + +{{< columns >}} +### {{< icon "gauge-high" >}}   Performance + +gRPC uses http/2 by default and is faster than REST. When using protocol buffers for encoding, the information comes on and off the wire much faster than JSON. Latency is an important factor in distributed systems. JSON encoding creates a noticeable factor of latency. For distributed systems and high data loads, gRPC can actually make an important difference. Other than that, gRPC supports multiple calls via the same channel and the connections are bidirectional. A single connection can transmit requests and responses at the same time. gRPC keeps connections open to reuse the same connection again which prevents latency and saves bandwidth. + +<---> +### {{< icon "helmet-safety" >}}   Robustness + +gRPC empowers better relationships between clients and servers. The rules of communication are strictly enforced. That is not the case in REST calls, where the client and the server can send and receive anything they like and hopefully the other end understands what to do with it. In gRPC, to make changes to the communication, both client and server need to change accordingly. This prevents mistakes specially in microservice architectures. +{{< /columns >}} +{{< columns >}} + +### {{< icon "magnifying-glass-plus" >}}   Debuggability + +gRPC requests are re-using the same context and can be tracked or traced across multiple service boundaries. +This helps to identify slow calls and see what is causing delays. It is possible to cancel requests which cancels +them on all involved services. + +<---> +### {{< icon "boxes-stacked" >}}   Microservices + +gRPC has been evolving and has become the best option for communication between microservices because of its unmatched +performance and its polyglot nature. One of the biggest strengths of microservices is the freedom of programming +languages and technologies. By using gRPC we can leverage all the advantages of strictly enforced communication +standards combined with freedom of choice between different programming languages - whichever would fit best. + +{{< /columns >}} + +{{< hint type=info title="gRPC Advantages" >}} + +- http/2 +- protocol buffers +- reusable connections +- multi language support +{{< /hint >}} + +## CS3 APIs + +{{< figure src="/ocis/static/cs3org.png" >}} + +The [CS3 APIs](https://github.com/cs3org/cs3apis) connect storages and application providers. + +The CS3 APIs follow Google and Uber API design guidelines, specially on error handling and naming convention. You can read more about these +guidelines at https://cloud.google.com/apis/design/ and https://github.com/uber/prototool/blob/dev/style/README.md. + +The CS3 APIs use [Protocol Buffers version 3 (proto3)](https://github.com/protocolbuffers/protobuf) as their +Interface Definition Language (IDL) to define the API interface and the structure of the payload messages. diff --git a/docs/ocis/static/cs3org.png b/docs/ocis/static/cs3org.png new file mode 100644 index 0000000000..6f06e21695 Binary files /dev/null and b/docs/ocis/static/cs3org.png differ diff --git a/docs/ocis/static/grpc-logo.png b/docs/ocis/static/grpc-logo.png new file mode 100644 index 0000000000..11ad9b1eb6 Binary files /dev/null and b/docs/ocis/static/grpc-logo.png differ diff --git a/docs/ocis/static/http-logo.png b/docs/ocis/static/http-logo.png new file mode 100644 index 0000000000..b37f746738 Binary files /dev/null and b/docs/ocis/static/http-logo.png differ diff --git a/docs/ocis/static/ocis-apis.drawio.svg b/docs/ocis/static/ocis-apis.drawio.svg new file mode 100644 index 0000000000..85721884e0 --- /dev/null +++ b/docs/ocis/static/ocis-apis.drawio.svg @@ -0,0 +1,286 @@ + + + + + + + +
+
+
+ Client 1 +
+
+
+ + + Client 1 + + + + + + + +
+
+
+ HTTP Gateway +
+ (proxy service) +
+
+
+ + + HTTP Gateway... + + + + + + + +
+
+
+ Client 2 +
+
+
+ + + Client 2 + + + + + + + +
+
+
+ Client 3 +
+
+
+ + + Client 3 + + + + + + + + + +
+
+
+ HTTP +
+
+
+ + + HTTP + + + + + + + + + +
+
+
+ HTTP +
+
+
+ + + HTTP + + + + + + + + + +
+
+
+ HTTP +
+
+
+ + + HTTP + + + + + + + +
+
+
+ ocis service +
+
+
+ + + ocis service + + + + + + + +
+
+
+ ocis service +
+
+
+ + + ocis service + + + + + + + +
+
+
+ ocis service +
+
+
+ + + ocis service + + + + + + + + + +
+
+
+ HTTP +
+
+
+ + + HTTP + + + + + + + +
+
+
+ GRPC Gateway +
+ (gateway service) +
+
+
+ + + GRPC Gateway... + + + + + + + + + +
+
+
+ gRPC +
+
+
+ + + gRPC + + + + + + + + + +
+
+
+ gRPC +
+
+
+ + + gRPC + + + + + + + + + +
+
+
+ HTTP +
+
+
+ + + HTTP + + + + + + + + + Viewer does not support full SVG 1.1 + + + + \ No newline at end of file