Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Better link language SDKs #6866

Merged
merged 2 commits into from
Jul 10, 2024
Merged

docs: Better link language SDKs #6866

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
80239af
docs: Better link language SDKs
charlieegan3 Jul 9, 2024
1d1f860
PR adjustments
charlieegan3 Jul 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/content/http-api-authorization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,12 @@ Then run `docker-compose` to pull and run the containers.
docker-compose -f docker-compose.yml up
```

{{< info >}}
This example shows conceptually a 'manual' REST API integration with OPA.
You might find it easier to build your OPA integration using one of the
[language SDKs](/ecosystem/#languages) than working with the REST API directly.
{{< /info >}}

Every time the demo web server receives an HTTP request, it
asks OPA to decide whether an HTTP API is authorized or not
using a single RESTful API call. An example code is [here](https://github.com/open-policy-agent/contrib/blob/main/api_authz/docker/echo_server.py),
Expand Down
13 changes: 8 additions & 5 deletions docs/content/integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ This page focuses predominantly on different ways to integrate with OPA's policy
OPA supports different ways to evaluate policies.

* The [REST API](../rest-api) returns decisions as JSON over HTTP.
* Also see the [Language SDKs](/ecosystem/#languages) for working with the REST API in different languages.
* The [Go API (GoDoc)](https://pkg.go.dev/github.com/open-policy-agent/opa/rego) returns
decisions as simple Go types (`bool`, `string`, `map[string]interface{}`,
etc.)
Expand All @@ -37,14 +38,16 @@ OPA supports different ways to evaluate policies.
* The [SDK](https://pkg.go.dev/github.com/open-policy-agent/opa/sdk) provides high-level APIs for obtaining the output
of query evaluation as simple Go types (`bool`, `string`, `map[string]interface{}`, etc.)


### Integrating with the REST API

To integrate with OPA outside of Go, we recommend you deploy OPA as a host-level
daemon or sidecar container. When your application or service needs to make
policy decisions it can query OPA locally via HTTP. Running OPA locally on the
same host as your application or service helps ensure policy decisions are fast
and highly-available.
daemon or sidecar container. Running OPA locally on the same host as your
application or service helps ensure policy decisions are fast and highly-available.

When your application or service needs to make policy decisions it can query OPA
locally via HTTP. While it's possible to call OPA's [REST API](../rest-api) directly,
you can also find a number of [native language REST SDKs](/ecosystem/#languages)
which make the integration easier.

#### Named Policy Decisions

Expand Down
16 changes: 11 additions & 5 deletions docs/content/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ groups:
* [Config API](#config-api) - view instance configuration.
* [Status API](#status-api) - view instance [status](../management-status) state.

The REST API is a very common way to integrate with OPA.
The REST API is a common way to integrate with OPA.
{{<
ecosystem_feature_link
key="rest-api-integration"
Expand All @@ -30,6 +30,12 @@ The REST API is a very common way to integrate with OPA.
You may also want to review the [integration documentation](../integration) for other options
to build on OPA by embedding functionality directly into your application.

{{< info >}}
Integrating with OPA from a programming language? You might find it easier to build your
OPA integration using one of the [language SDKs](/ecosystem/#languages) than working
with the REST API directly.
{{< /info >}}

## Policy API

The Policy API exposes CRUD endpoints for managing policy modules. Policy modules can be added, removed, and modified at any time.
Expand Down Expand Up @@ -1316,9 +1322,9 @@ Partially evaluate a query.
The [Compile API](#compile-api) allows you to partially evaluate Rego queries
and obtain a simplified version of the policy. This is most useful when building
integrations where policy logic is to be translated and evaluated in another
environment. For example,
environment. For example,
[this post](https://blog.openpolicyagent.org/write-policy-in-opa-enforce-policy-in-sql-d9d24db93bf4)
on the OPA blog shows how SQL can be generated based on Compile API output.
on the OPA blog shows how SQL can be generated based on Compile API output.
For more details on Partial Evaluation in OPA, please refer to
[this blog post](https://blog.openpolicyagent.org/partial-evaluation-162750eaf422).

Expand Down Expand Up @@ -2178,6 +2184,6 @@ OPA currently supports the following query provenance information:

## Ecosystem Projects

OPA's REST API has already been used by many projects in the OPA Ecosystem to support a variety of use cases.
OPA's REST API has already been used by many projects in the OPA Ecosystem to support a variety of use cases.

{{< ecosystem_feature_embed key="rest-api-integration" topic="built on the OPA REST API" >}}
{{< ecosystem_feature_embed key="rest-api-integration" topic="built on the OPA REST API" >}}