Merge pull request #239 from ynput/Add-AYON-APIs-&-Components

Add AYON APIs & Resources section

website/docs/dev_api_cpp.md

@@ -0,0 +1,120 @@
+---
+id: dev_api_cpp
+title: AYON C++ API
+sidebar_label: C++ API
+description: Information about AYON C++ API
+toc_max_heading_level: 5
+---
+
+## About AYON C++ API
+
+The AYON CPP API allows communication with the AYON server.
+Implementation is mainly focused on [AYON USD Resolver](dev_api_usd_resolver.md) to communicate with the server resolve endpoint.
+
+## Get Started
+
+:::tip Development Environment
+We assume you already have setup your c++ dev environment as well as cmake.
+:::
+
+### Fetch and Build The library
+AYON CPP API is a static lib.
+
+You need to build it first. We've prepared python script to do the hard lifting for you.
+
+```shell
+git clone --recurse-submodules https://github.com/ynput/ayon-cpp-api.git
+cd ayon-cpp-api
+python AyonBuild.py setup 
+python AyonBuild.py runStageGRP CleanBuild
+```
+
+### Include it in your cmake projects
+
+Once you include it and build your cpp project you'll no longer need the library.
+
+<details><summary>A CPP Example</summary>
+
+Here's an example cpp project structure
+```
+.
+├─ ext/ayon-cpp-api
+├─ CMakelists.txt
+└─ main.cpp
+```
+
+#### Fetch Dependencies
+
+Please refer to [Fetch and Build The library](dev_api_cpp#fetch-and-build-the-library) section above for the instructions
+and repeat them inside `ext` folder in your project folder.
+
+#### CPP Project Files
+
+```cpp title="main.cpp"
+// AYON CPP API Test
+#include "AyonCppApi.h"
+
+int main (){
+    AyonApi con = AyonApi();
+    return 0;
+}
+```
+
+```shell title="CMakelists.txt"
+cmake_minimum_required(VERSION "3.28.1")
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED True)
+
+project(main)
+
+# Include AyonCppApi 
+add_subdirectory("${CMAKE_CURRENT_SOURCE_DIR}/ext/ayon-cpp-api")
+include_directories("${CMAKE_CURRENT_SOURCE_DIR}/ext/ayon-cpp-api")
+
+add_executable(${PROJECT_NAME} main.cpp)
+
+target_link_libraries(${PROJECT_NAME} AyonCppApi)
+```
+
+#### Build the project
+
+> I'm using `VS studio` (devenv.exe) on my side.
+
+```shell
+cmake -S . -B build -DJTRACE=0 
+devenv build/main.sln /Build 
+```
+
+#### Test Run
+
+you'd need to set few environment variables.
+otherwise, it won't work.
+
+```shell
+set AYON_SERVER_URL=<your ayon server url>
+set AYON_API_KEY=<your server api key>
+set AYON_PROJECT_NAME=<project name>
+set AYON_SITE_ID=<site id>  # e.g. military-mouse-of-jest
+
+build\Debug\main.exe
+```
+
+Expected Output
+```shell
+my_cpp_project> build\Debug\main.exe
+[2024-09-20 15:59:31.541] [info] Loaded AYON_API_KEY and AYON_SERVER_URL
+[2024-09-20 15:59:31.542] [info] Found SideId
+```
+
+:::tip `AYON_SITE_ID` fallback
+When skipping setting `AYON_SITE_ID` env variable, the lib will default to file named `site_id` *without an extension*.
+located at `%AppData%/Roaming/AYON/site_id` on windows.
+:::
+
+</details>
+
+## Learn More
+
+For More info and a full list of available commands
+Please refer to our [AYON CPP API](https://ynput.github.io/ayon-cpp-api/).

website/docs/dev_api_graphql.md

@@ -0,0 +1,82 @@
+---
+id: dev_api_graphql
+title: AYON GraphQL API
+sidebar_label: GraphQL API
+description: Information about AYON GraphQL API
+toc_max_heading_level: 5
+---
+
+## What is GraphQL?
+
+GraphQL is a query language between frontend and backend. it allows you to expose the data sent from server to client
+
+GraphQL is a query language and server-side runtime for application programming interfaces (APIs) that gives API clients exactly the data they requested. As an alternative to REST, GraphQL allows developers to make requests to fetch data from multiple data sources with a single API call.
+
+You can use GraphQL and REST APIs interchangeably. 
+
+You have limited bandwidth, and you want to minimize the number of requests and responses
+You have multiple data sources, and you want to combine them at one endpoint
+You have client requests that vary significantly, and you expect very different responses
+
+interrelated data
+
+## About GraphQL and AYON
+
+Each GraphQl call is constructed from a schema which describes the data to work with.
+
+There are two main root types of schemas:
+1. Query: Read
+2. Mutation: Create, update or Delete
+
+Currently, AYON supports only Query Root type where you can fetch data directly from AYON's Backend.
+
+To perform any operations or mutation please consider using our [REST API](dev_api_rest.md) instead.
+
+## AYON GraphQL Explorer
+
+While you can access GraphQL from code, you can also access it via your AYON Web UI as we integrate `GraphiQL`, an in-browser tool for writing, validating, and testing GraphQL queries.
+
+<div class="row markdown">
+<div class="col col--6 markdown">
+
+You access the GraphQL Explorer via `<your-ayon-server-url>/graphiql` or via help icon.
+
+</div>
+<div class="col col--6 markdown">
+
+![](assets/apis_and_resources/graphql_explorer.png)
+
+</div>
+</div>
+
+
+### AYON GraphQL Explorer UI
+
+![](assets/apis_and_resources/graphql_explorer_ui.png)
+1. GraphiQL Bar:
+   - ▶️ Button: Execute Query (ctrl+Enter)
+   - Prettify: It formats your input.
+   - History: Shows your queries history.
+   - Explorer: Opens Explorer window, you can use it to construct queries. It's also can be an alternative to Docs as it shows supported queries.
+   - Docs: It shows Documentation Explorer.
+2. Input Box: Where you add your GraphQL queries.
+3. Output Box: Shows the output.
+
+
+## Your First AYON query
+Here's a simple query to try out. 
+When executed it returns a list of the current projects names and whether or not they are active.
+```graphql
+query MyQuery {
+  projects {
+    edges {
+      node {
+        name
+        active
+      }
+    }
+  }
+}
+```
+
+![](assets/apis_and_resources/graphql_example.png)

website/docs/dev_api_python.md

@@ -0,0 +1,45 @@
+---
+id: dev_api_python
+title: AYON Python API
+sidebar_label: Python API
+description: Information about AYON Python API
+toc_max_heading_level: 5
+---
+
+## About AYON Python API
+
+A Python client for connecting to AYON server using `requests` module. Wraps REST API endpoints including GraphQl to communicate with server.
+
+The module supports singleton connection which is using `AYON_SERVER_URL` and `AYON_API_KEY` environment variables as source for connection. But you can create multiple connection to different servers using `ServerAPI` class.
+
+## Get Started 
+You only need to get the python module to get started.
+```
+pip install ayon-python-api
+```
+Then, you can make your first API call from your code editor by running
+```python
+import os
+import ayon_api
+
+# Set necessary environment variables
+os.environ["AYON_SERVER_URL"] = "<your-ayon-server-url>"
+os.environ["AYON_API_KEY"] = "<your-ayon-api-key>"
+
+# Make the connection
+con = ayon_api.get_server_api_connection()
+
+# Get a list of available projects
+projects = con.get_projects()
+print(projects)
+```
+
+:::tip
+You can find more examples in the following Community guide on forums.
+[AYON Python API First Steps](https://community.ynput.io/t/ayon-python-api-first-steps/1278)
+:::
+
+## Learn More
+
+For More info and a full list of available commands
+Please refer to our [AYON Python API Docs](https://ynput.github.io/ayon-python-api/).

website/docs/dev_api_rest.md

@@ -0,0 +1,72 @@
+---
+id: dev_api_rest
+title: AYON REST API
+sidebar_label: REST API
+description: Information about AYON Rest API
+toc_max_heading_level: 5
+---
+
+## What is a REST API?
+
+REST is a short name for `RESTful` which is a programming interface that allows you to communicate with web servers via `HTTP` requests to access and use data.
+HTTP requests include `POST` (create), GET (read), `PUT` (update) and DELETE data.
+
+These 4 types of requests form the famous terminology `CRUD`: Create, Read, Update and Delete.
+
+## AYON REST API
+
+You can use `AYON REST API` to manipulate AYON Resources.
+e.g. you can use it to get a list of projects or create new projects, get a list of current users or add users and manage resources e.g. download or upload AYON Launcher, addons and dependency packages.
+
+Each AYON server generates docs for its REST API as they can be extended via [Addons Devolvement](dev_addon_creation.md#end-points)
+
+You access the REST API Docs via `<your-ayon-server-url>/api` or via help icon.
+
+![](assets/apis_and_resources/rest_api_docs.png)
+
+For instance, you can check the REST API Docs for our Public AYON Server here at [AYON REST API Docs](/api)
+
+## Your First AYON API Calls
+
+:::tip
+Examples in this section were brought from the following Community guide.
+Feel free to check it and delve into discussions.
+
+[AYON REST API Guide](https://community.ynput.io/t/ayon-rest-api-guide/1268)
+:::
+
+Let's do our first api calls where we will login into AYON and get a list available projects.
+For this purpose consider using a REST client such as [postman](https://www.postman.com/) or [VsCode Thunder Client](https://marketplace.visualstudio.com/items?itemName=rangav.vscode-thunder-client).
+
+For the following example, I'll stick to `VsCode Thunder Client`.
+
+### Login into AYON
+1. Write a login request: `<your-ayon-server-url>/api/auth/login`
+2. Add name and password
+3. Send
+4. Find the token.
+
+![](assets/apis_and_resources/rest_login.png)
+
+### Get list of projects
+> You'll need the token from the last call.
+ 
+1. write a login request: `<your-ayon-server-url>/api/projects`
+2. Add your token
+3. Send
+4. Find the available projects.
+
+![](assets/apis_and_resources/rest_get_projects.png)
+
+### Conclusion
+As you may have noticed, using the API, sending and processing the data is not meant to be read and processed by Humans. 
+we should do that with the aid of scripts where we can deal with them from a higher perspective where we can use a command like `get_projects_names` and it should use the proper API call and process the output for us.
+and, that's why REST API is called a programming interface.
+
+:::tip
+While AYON REST API solely doesn't process the data for us.
+You would need to write the essential code to make the API call
+and then process the data before displaying it for you.
+For example check [AYON REST API Guide](https://community.ynput.io/t/ayon-rest-api-guide/1268) to
+explore different ways to make REST API calls.
+:::

website/docs/dev_api_usd_resolver.md

@@ -0,0 +1,28 @@
+---
+id: dev_api_usd_resolver
+title: AYON USD Resolver
+sidebar_label: USD Resolver
+description: Information about AYON USD Resolver.
+toc_max_heading_level: 5
+---
+
+## AYON USD Resolver Project
+
+The Ayon USD Resolver enables resolution of Ayon URIs and pinning files using Pixar's Open USD.
+It's designed to turn URIs with the `ayon://` or `ayon+entity://` formats into local file paths.
+
+:::tip AYON USD Resolver Standard
+
+AYON USD Resolver is an [AR2.0](https://openusd.org/release/wp_ar2.html) resolver and will not support AR1.0 resolution.
+Make sure that your software package is compatible with the `AR2.0` standard or use the **defaults** we provide in the [AYON USD Addon](https://github.com/ynput/ayon-usd)
+:::
+
+
+## Get Started
+
+For the info about get started please refer to [Getting Started](https://ynput.github.io/ayon-usd-resolver/md_md_Getting_Started.html) in our AYON USD Resolver Docs.
+
+
+## Learn More
+
+For More info, please refer to our documentation for [AYON USD Resolver](https://ynput.github.io/ayon-usd-resolver/)

website/docs/dev_components_react.md

@@ -0,0 +1,36 @@
+---
+id: dev_components_react
+title: AYON Frontend React Components
+sidebar_label: Frontend React Components
+description: Information about AYON frontend react components
+toc_max_heading_level: 5
+---
+
+## About AYON React Components
+
+The [AYON Component Library](https://github.com/ynput/ayon-react-components) is a collection of components for the AYON project. It's extensively used in our [ayon-frontend](https://github.com/ynput/ayon-frontend), the React frontend code for the Ayon server.
+It can be used to create consistent and accessible AYON addons.
+
+## Get Started
+
+You can find examples for creating a Frontend React App for addons in [Addon Frontend Dev](dev_addon_creation.md#react-app).
+Once set up, you can try different AYON components.
+
+:::tip
+Our [AYON React Components Docs](https://components.ayon.dev/?path=/docs/button--docs) provide examples you can copy and paste directly into your React app for easy experimenting.
+
+Remember to import the component into your code, as it's not copied by default. For the following [EntityCard](https://components.ayon.dev/?path=/docs/entitycard--docs) example in the screen grab, use:
+
+```js
+import { EntityCard } from '@ynput/ayon-react-components'
+```
+
+![](assets/apis_and_resources/copying_react_examples.gif)
+:::
+
+## Learn More
+You can find the full list of components and their documentation at [AYON React Components Docs](https://components.ayon.dev/?path=/docs/button--docs)
+
+:::tip
+To run Documentation locally follow [Get Started with Storybook](https://github.com/ynput/ayon-react-components?tab=readme-ov-file#get-started-with-storybook) on GitHub.
+:::