Chapter 1. Introduction

GET requests are used to retrieve a resource configuration if that resource is specified by name in the target URL.
For example, a GET request to {$OCP_CLUSTER}/oapi/namespaces/{$PROJECT}/routes/{$ROUTE} returns that {$ROUTE} configuration.

Alternatively, GET requests to resource collections return the list objects in that resource collection.
For example, a GET request to {$OCP_CLUSTER}/oapi/namespaces/{$PROJECT}/routes returns a list of the routes in the {$PROJECT} namespace.

GET requests do not require a request body.

POST requests are used to create new resources based on the configuration in the request body.
For example, a POST request with a new route configuration in the request body to {$OCP_CLUSTER}/api/namespaces/{$PROJECT}/routes creates a new route in the {$PROJECT} namespace.

PUT requests are used to update or modify configurations. A PUT request targets specific resources and requires a complete and modified configuration in the request body.
For example, A PUT request to with a complete route configuration that has had one or more field values updated to {$OCP_CLUSTER}/oapi/namespaces/{$PROJECT}/routes/{$ROUTE} will replace that {$ROUTE} configuration.

PATCH requests are used to selectively update or modify field values in a resource configuration. How the change is merged is defined per field.

PATCH requests require JSON formatting and Content-Type: header text/strategic-merge-patch+json.
For example, a PATCH request with the following request body:

{
  "spec": {
     "to": {
      "weight": 1
     }
  }
}

{
  "spec": {
     "to": {
      "weight": 1
     }
  }
}

to {$OCP_CLUSTER}/oapi/namespaces/{$PROJECT}/routes/{$ROUTE} will update the weight of that route to 1.

DELETE requests are used to remove resource configurations.
For example, a request to {$OCP_CLUSTER}/oapi/namespaces/{$PROJECT}/routes/{$ROUTE} removes that route from the {$PROJECT} namespace.

DELETE requests do not require a request body.

Request bodies are typically shown in their simplest form. Detailed object configurations can be found in the Resource Examples chapter. Comprehensive information for each API object can be found in the REST API Reference Guide.

Request and response body snippets are used in some examples. These snippets use ellipses (…​) to delimit the relevant content from the redacted parts of the example configuration.

Request headers use generic {$BEARER_TOKEN} and {$OCP_CLUSTER} variables in place of the request authentication bearer token hash, and the OpenShift cluster hostname in the request target url, respectively.

An example OpenShift cluster hostname is:

https://openshift.example.com:8443

https://openshift.example.com:8443

Additional variables are included in place of object names. For example, {$PROJECT} is commonly used in place of a particular namespace.

Request examples in this guide use YAML for readability, and application/yaml is specified in the Accept: and Content-Type: headers to accommodate this. However, PATCH requests require JSON formatting and are documented as such.