Getting started with the Code Engine REST API

You can use the IBM Cloud® Code Engine API to create and manage your Code Engine entities.

Setting up your API environment

To work with the API to create and manage Code Engine entities, set up your API environment.

Before you begin, download and install the jq tool, which is a lightweight and flexible command-line JSON processor. This tool makes it easier to work with JSON responses that you receive from Code Engine API.

Set values for region, api_key, and project_name before you run the example Curl commands in the API. For example,
```
region=us-south
api_key=YOUR_IBM_CLOUD_API_KEY
project_name=MY_PROJECT_NAME
```
- To discover the IBM Cloud region that you're logged in to, run the ibmcloud region command.
- For more information about IBM Cloud API keys, see Managing user API keys.
- For more information about Code Engine projects, see Managing projects.

Check that you have a valid IBM Cloud® Identity and Access Management (IAM) access token. For more information about IAM API, see Create an IAM access token for a user or service ID by using an API key.

token=`curl -X POST "https://iam.cloud.ibm.com/identity/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=urn:ibm:params:oauth:grant-type:apikey" \
  -d "apikey=${api_key}" \
  | jq .access_token -r`

Use the authentication token and the variables that you defined in step 1 to retrieve the project ID of your project. In the following example, use curl with jq to parse the Code Engine API response and save the project ID in a variable. For example,
```
project_id=`curl -X GET "https://api.${region}.codeengine.cloud.ibm.com/v2/projects" \
   -H "Authorization: ${token}" \
   | jq --arg project_name ${project_name} '.projects[] | select(.name == $project_name) | .id' -r`
```

Working with a Code Engine application in the API

Now that your Code Engine API environment is set up, you are ready to work with Code Engine entities, such as applications or jobs. In the following scenario, let's create an application, access it, and then delete the application.

Create an app. Use the previously set variables and the project ID to construct a URL and send a request to create the my-app application. For example,

curl -X POST "https://api.${region}.codeengine.cloud.ibm.com/v2/projects/${project_id}/apps" \
  -H "Authorization: ${token}" \
  -H "Content-Type: application/json" \
  -d '{ \
    "name": "my-app", \
    "image_reference": "icr.io/codeengine/helloworld" \
  }'

To display details about the my-app application, send a GET request. Be sure to reference the name of your app. Note that the last line of jq is optional, though it makes the output more readable.

curl -X GET "https://api.${region}.codeengine.cloud.ibm.com/v2/projects/${project_id}/apps/my-app" \
  -H "Authorization: ${token}" \
  -H "Content-Type: application/json" \
  | jq .

To delete the application, send the request again but this time, use the DELETE method instead of the GET method.

curl -X DELETE "https://api.${region}.codeengine.cloud.ibm.com/v2/projects/${project_id}/apps/my-app" \
  -H "Authorization: ${token}" \
  -H "Content-Type: application/json"

(Optional) If you send another GET request to retrieve information about my-app, then you receive a 404 error because the resource no longer exists.

Example output

{
  "errors": [
    {
      "code": "resource_not_found",
      "message": "Resource not found."
    }
  ],
  "trace": "codeengine-api-34dc0040429941de8c9e02f0f1200af1",
  "status_code": 404
}

Next steps

Now that you have setup your environment and taken the first steps with a Code Engine application with the API, are you ready to further explore the Code Engine API?

For more information and examples for Code Engine SDKs in several languages, see the Code Engine API documentation.

To start working with Code Engine components with the API, see

IBM Cloud® Code Engine is designed so that you do not need to interact with the underlying technology it is built upon. However, if you have existing tools that are based on Kubernetes or Knative, you can still use it with Code Engine. Code Engine supports the Knative and Kubernetes APIs and their CLI commands. For more information, see Using Kubernetes with Code Engine and Using Knative with Code Engine.