diff --git a/docs/.gitignore b/docs/.gitignore index 02053cc8227..58ffe8ed3f9 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,4 +1,4 @@ hugo/ -grpc_apis/ +/**/grpc_apis/ocis/ mutagen.yml.lock -helpers/output/* \ No newline at end of file +helpers/output/* diff --git a/docs/apis/_index.md b/docs/apis/_index.md new file mode 100644 index 00000000000..f1792dc1b03 --- /dev/null +++ b/docs/apis/_index.md @@ -0,0 +1,3 @@ +--- +title: APIs +--- diff --git a/docs/apis/grpc_apis/_index.md b/docs/apis/grpc_apis/_index.md new file mode 100644 index 00000000000..3dd2acefd35 --- /dev/null +++ b/docs/apis/grpc_apis/_index.md @@ -0,0 +1,11 @@ +--- +title: gRPC +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/apis/grpc_apis/ +geekdocFilePath: _index.md +geekdocCollapseSection: true +--- + +## **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. diff --git a/docs/apis/http/_index.md b/docs/apis/http/_index.md new file mode 100644 index 00000000000..c64ba1e4a07 --- /dev/null +++ b/docs/apis/http/_index.md @@ -0,0 +1,11 @@ +--- +title: Http +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/apis/http/ +geekdocFilePath: _index.md +geekdocCollapseSection: true +--- + +The [Hypertext Transfer Protocol (HTTP)](https://www.rfc-editor.org/rfc/rfc2616) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. HTTP is the foundation of data communication for the World Wide Web, where hypertext documents include hyperlinks to other resources that the user can easily access, for example by a mouse click or by tapping the screen in a web browser. + +Development of HTTP was initiated by Tim Berners-Lee at CERN in 1989 and summarized in a simple document describing the behavior of a client and a server using the first HTTP protocol version that was named 0.9. That first version of HTTP protocol soon evolved into a more elaborated version that was the first draft toward a far future version 1.0 diff --git a/docs/apis/http/graph/_index.md b/docs/apis/http/graph/_index.md new file mode 100644 index 00000000000..1bf37998a1c --- /dev/null +++ b/docs/apis/http/graph/_index.md @@ -0,0 +1,66 @@ +--- +title: "LibreGraph" +date: 2018-05-02T00:00:00+00:00 +weight: 20 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/apis/http/graph +geekdocFilePath: _index.md +geekdocCollapseSection: true +--- + +The LibreGraph API is a REST Api which is inspired by the [Microsoft Graph API](https://developer.microsoft.com/en-us/graph). It tries to stay compliant with the Microsoft Graph API and aims to be the Next Generation Api in Infinite Scale where we want to support most of the features of the platform. +The [API specification](https://github.com/owncloud/libre-graph-api) is available in the OpenApi 3 standard and there are generated client and server [SDKs](https://github.com/owncloud/libre-graph-api#clients) available. You can browse the API with the [Swagger UI](https://owncloud.dev/libre-graph-api/). + +## Calling the LibreGraph API + +```sh +{HTTP method} https://ocis.url/graph/{version}/{resource}?{query-parameters} +``` + +The request component consists of: + +| Component | Description | +|--------------------|-------------------------------------------------------------------------| +| {HTTP method} | The HTTP method which is used in the request. | +| {version} | The version of the LibreGraph API used by the client. | +| {resource} | The LibreGraph Resource which the client is referencing in the request. | +| {query-parameters} | Optional parameters for the request to customize the response. | + +### HTTP methods + +| Method | Description | +|--------|-------------------------------| +| GET | Read data from a resource. | +| POST | Create a new resource. | +| PATCH | Update an existing resource. | +| PUT | Replace an existing resource. | +| DELETE | Delete an existing resource. | + +The methods `GET` and `DELETE` need no request body. The methods `POST`, `PATCH` and `PUT` require a request body, normally in JSON format to provide the needed values. + +### Version + +Infinite Scale currently provides the version `v1.0`. + +### Resource + +A resource could be an entity or a complex type and is usually defined by properties. Entities are always recognizable by an `Id` property. The URL contains the resource which you are interacting with e.g. `/me/drives` or `/groups/{group-id}`. + +Each resource could possibly require different permissions. Usually you need permissions on a higher level for creating or updating an existing resource than for reading. + +### Query parameters + +Query parameters can be OData system query options, or other strings that a method accepts to customize its response. + +You can use optional OData system query options to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method. + +For example, adding the following filter parameter restricts the drives returned to only those with the driveType property of `project`. + +```shell +GET https://ocis.url/graph/v1.0/drives?$filter=driveType eq 'project' +``` +For more information about OData query options please check the [API specification](https://github.com/owncloud/libre-graph-api) and the provided examples. + +## Resources + +{{< toc-tree >}} diff --git a/docs/services/graph/groups.md b/docs/apis/http/graph/groups.md similarity index 100% rename from docs/services/graph/groups.md rename to docs/apis/http/graph/groups.md diff --git a/docs/services/graph/spaces.md b/docs/apis/http/graph/spaces.md similarity index 100% rename from docs/services/graph/spaces.md rename to docs/apis/http/graph/spaces.md diff --git a/docs/services/graph/users.md b/docs/apis/http/graph/users.md similarity index 100% rename from docs/services/graph/users.md rename to docs/apis/http/graph/users.md diff --git a/docs/grpc_apis/_index.md b/docs/grpc_apis/_index.md deleted file mode 100644 index f6588c8d7f9..00000000000 --- a/docs/grpc_apis/_index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: GRPC apis ---- diff --git a/protogen/docs/GRPC.tmpl b/protogen/docs/GRPC.tmpl index b7262c5d099..797cb442b99 100644 --- a/protogen/docs/GRPC.tmpl +++ b/protogen/docs/GRPC.tmpl @@ -1,7 +1,7 @@ --- {{- $package := (index .Files 0).Package }} title: "{{ $package }}" -url: /grpc_apis/{{ $package | replace "." "_" }} +url: /apis/grpc_apis/{{ $package | replace "." "_" }} date: {{ now | date "2006-01-02T15:04:05Z07:00" }} weight: 50 geekdocRepo: https://github.com/owncloud/ocis @@ -28,7 +28,7 @@ geekdocRepo: https://github.com/owncloud/ocis {{- if and (hasPrefix "ocis." .LongType) (ge (len $filenameParts) 3) -}} {{- $ltypeSpl := .LongType | splitList "." -}} {{- $ltypePkg := slice $ltypeSpl 0 (sub (len $ltypeSpl) 1) | join "_" -}} - {{- $loca = printf "/grpc_apis/%s/#%s" $ltypePkg (.Type | lower) -}} + {{- $loca = printf "/apis/grpc_apis/%s/#%s" $ltypePkg (.Type | lower) -}} {{- end -}} | {{.Name}} | [{{.LongType}}]({{ $loca }}) | {{.Label}} | {{ .Description | replace "\n" "
" }}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end }} | {{ end -}} @@ -61,7 +61,7 @@ geekdocRepo: https://github.com/owncloud/ocis {{ range .Extensions -}} | {{.Name}} | {{.LongType}} | {{.ContainingLongType}} | {{.Number}} | {{ .Description | replace "\n" "
" }}{{if .DefaultValue}} Default: `{{.DefaultValue}}`{{end}} | {{ end -}} -{{ end -}} +{{ end -}} {{- range .Services }} ### {{ .Name }}