# Manage resources

Learn how to manage resources using the HTTP API.

## Introduction

Your data such as products, customers, carts, and orders are stored as JSON document resources in a Project.
The resources in a Project are isolated from resources in other Projects hosted in the same [Region](/api/general-concepts.md#regions) and only authorized clients have access to them.
You can manage the resources in your Project through [authorized API clients](/api/authorization.md) over HTTP or through the Merchant Center.

Each API request to a resource in your [Project](/api/general-concepts.md#project) must contain the `projectKey`, a unique identifier of your Project.

```http
https://api.{region}.commercetools.com/{projectKey}
```

To manage resources in your Project, the HTTP API provides the typical CRUD (Create, Read, Update, Delete) methods for each type of resource.

Additionally, Search APIs are available that are optimized for discovery and lookup of a large number of resources of the same type.
These and the Product Projection API provide read methods only and their data is kept up to date by background processes running in the platform.

The HTTP API comes in two flavors: [REST](/api/getting-started/manage-resources.md#rest) and [GraphQL](/api/getting-started/manage-resources.md#graphql).

### REST

The REST API offers dedicated endpoints of each resource type indicated in the path.

```http
https://api.{region}.commercetools.com/{projectKey}/{resources}
```

To manage a particular resource, append its unique [identifier](/api/general-concepts.md#identifier) to the path.

```http
https://api.{region}.commercetools.com/{projectKey}/{resources}/{id}
```

```http
https://api.{region}.commercetools.com/{projectKey}/{resources}/key={key}
```

Compliant to [REST maturity level 2](https://en.wikipedia.org/wiki/Richardson_Maturity_Model), the API uses the HTTP verbs `GET`, `POST`, and `DELETE` to express the CRUD methods:

```http title="Read resources"
GET https://api.{region}.commercetools.com/{projectKey}/{resources}
```

```http title="Create or Update resources"
POST https://api.{region}.commercetools.com/{projectKey}/{resources}
```

```http title="Delete resources"
DELETE https://api.{region}.commercetools.com/{projectKey}/{resources}
```

The REST API uses `POST` requests for updates on resources, instead of `PUT` or `PATCH`, to follow the  Command Query Responsibility Segregation (CQRS) pattern.
To ensure a good performance of Update operations, the API provides dedicated update actions for the fields of the resources.

#### Resource-specific endpoints

The `{resources}` path parameter determines what resource type is targeted, for example:

| Endpoint | Accesses |
| --- | --- |
| `/customers` | Your Customer data. |
| `/products` | All of your Products and Product Variants. |
| `/orders` | Your Order data. |

```http title="Example URL for the Query Customers endpoint"
GET https://api.{region}.commercetools.com/{projectKey}/customers
```

An HTTP GET request to this URL with the Authorization header returns all your Customer data.

#### Query parameters

To handle a vast number of resources in our Project efficiently, you can append query parameters to the endpoint to use [query features](/api/general-concepts.md#query-features) such as filtering, sorting, and paginating the results.

When querying single resources (such as a specified Customer or Product), those query parameters will be ignored as a single JSON object is returned.

### GraphQL

The alternative way for managing resources in your project is through [GraphQL](https://graphql.org/) queries and mutations.
GraphQL fits well if you want to restrict your API responses to exactly what you want to retrieve.
In the RESTful way, you receive the entire resource always and have to extract the fields you are interested with your client application.
Because the filtering happens server-side, GraphQL queries have a slightly longer response time compared to RESTful requests.

All the resources in your Project are managed through the same [GraphQL endpoint](/api/graphql.md#query-graphql), REST APIs instead have dedicated endpoints per resource and method.
The [GraphQL schema](https://github.com/commercetools/commercetools-api-reference/tree/main/api-specs/graphql) contains the queries and mutations matching the REST API methods.
Because of the similarity in naming, we currently do not provide a detailed API reference documentation for GraphQL queries and mutations.
When you find a REST API method suitable for your use case in the API reference documentation, look for a method with this name in the Merchant Center's [GraphQL Explorer](/merchant-center/developer-settings.md#graphql-explorer) to find the corresponding GraphQL query.
In case the name differs significantly between REST and GraphQL, the documentation page contains a hint about the difference.

You can learn how to manage resources through this interface in the [GraphQL API reference documentation](/api/graphql.md). The remainder of this document focuses on the REST API.

## Read resources

The REST API offers two ways for retrieving resources from your Project.
If you know the [identifier](/api/general-concepts.md#identifier) of a resource, you can read it by performing a [Get Resource](/api/getting-started/manage-resources.md#get-a-resource) method.
The API then returns the JSON representation of this particular resource in its current state.

You cannot read a previous version of a resource, but you can retrieve a [history of changes](/api/history/overview.md) that have been made to a resource for most of the resource types.

If you don't know the identifier of a resource yet, but you want to retrieve them based on certain criteria, use a [Query Resources](/api/getting-started/manage-resources.md#query-resources) method.
For such method, the API returns a [paged query result](/api/general-concepts.md#pagedqueryresult), containing the resources that match the criteria you specified.

### Get a resource

Get Resource endpoints retrieve a specific resource by its [identifier](/api/general-concepts.md#identifier), that can be `id` or `key`.

```http title="Get Resource by ID"
GET https://api.{region}.commercetools.com/{projectKey}/resources/{ID}
Authorization: Bearer {access_token}
```

```http title="Get Resource by key"
GET https://api.{region}.commercetools.com/{projectKey}/resources/key={key}
Authorization: Bearer {access_token} 
```

### Query resources

Query endpoints retrieve multiple resources based on certain criteria specified in a [query predicate](/api/predicates/query.md).
If you omit the query predicate, you can read a collection of all resources of a type with such endpoint.
Query features such as [sorting](/api/general-concepts.md#sorting) and [pagination](/api/general-concepts.md#pagination) help you iterating over your collection of resources.

```http title="Query all Resources"
GET https://api.{region}.commercetools.com/{projectKey}/resources
Authorization: Bearer {access_token}
```

```http title="Query Resources with filtering on specific field value"
GET https://api.{region}.commercetools.com/{projectKey}/resources?where=fieldName="fieldValue"
Authorization: Bearer {access_token} 
```

## Write resources

Writing resources in the HTTP API involves creating, updating, or deleting resources. Each of these operations has its own specific endpoint and requirements. The HTTP API responds to these operations by returning the created, updated, or deleted resource.

### Create resources

You create a resource by posting a **Resource draft** to the Create Resource endpoint of the respective resource type.
The Resource draft is a JSON document in which you include the **user-defined fields** the created resource should have.
Some fields you must provide, others can be optional.
The API response contains the created **Resource** with additional fields the **platform generated** automatically, such as `id`, `version`, `createdAt`, and `lastModifiedAt`.

```mermaid
graph LR
	A(
		<strong>Resource draft</strong><br/>
		--- contains ---<br/>
		<strong>user-defined fields</strong><br/>
		key<br/>
		name<br/>
		...
	)

	B(
		<strong>Resource</strong><br/>
		--- contains ---<br/>
		<strong>user-defined fields</strong><br/>
		key, name<br/>
		--- plus ---<br/>
		<strong>platform-generated fields</strong><br/>
		id, version<br/>
		createdAt, lastModifiedAt
	)

	A -- Create Resource --> B

	style A fill:#FFC107,stroke:#E0E0E0,color:#212121,stroke-width:1px
	style B fill:#F5F5F5,stroke:#E0E0E0,color:#212121,stroke-width:1px
	linkStyle 0 stroke:#00A452,stroke-width:2px
```

For example, to create a new Customer, you post a [CustomerDraft](/search.md?urn=ctp:api:type:CustomerDraft) to the [Create Customer endpoint](/search.md?urn=ctp:api:endpoint:/{projectKey}/customers:POST).

```http title="Create a Customer"
POST https://api.{region}.commercetools.com/{projectKey}/customers
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email" : "johnsmith@example.com",
  "password" : "Nf7$kP!2wLz@9qXe"
}
```

### Update resources

To update resources with the API, such as changing a field or adding a new value for a field, you specify with individual [update actions](/api/general-concepts.md#resource-updates) which field of the resource you want to update.
Each resource type has its own set of update actions that can be used to modify it. For example, to change a Customer's name, you can use the [Set First Name](/api/projects/customers.md#set-first-name) and [Set Last Name](/api/projects/customers.md#set-last-name) update actions.

To support [optimistic concurrency control](/api/general-concepts.md#optimistic-concurrency-control), the current `version` of the resource to update must be provided together with the update actions.
To update several fields of the resource at the same time, you batch the corresponding update actions in the `actions` array of the request payload.

The resource to update is identified via a path parameter in the URI you append to the POST request to the resource type's endpoint.

```http title="Update a Customer's name"
POST https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "version": 1,
  "actions": [
    {
      "action": "setFirstName",
      "firstName": "John"
    },
    {
      "action": "setLastName",
      "lastName": "Smith"
    }
  ]
}
```

Optional fields can be unset by sending an update action with an empty value.

### Delete resources

To delete a resource with the API, make a **DELETE** request to the resource's endpoint and append the resource identifier as path parameter in the URI.
You must include the current `version` of the resource to delete as query parameter.

```http title="Delete a Customer"
DELETE https://api.{region}.commercetools.com/{projectKey}/customers/{customerID}?version=1
Authorization: Bearer {access_token}
```

Personal data associated with a resource [can be deleted in accordance with GDPR](/api/gdpr.md#data-erasure-of-personal-data) with an optional `dataErasure` parameter.

Some resources hold references to other resources. Attempting to delete a referenced resource before removing the resources that depend on it may result in errors.

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Make your first API call](/api/getting-started/make-first-api-call.md)
- [Next page: Import and export](/api/getting-started/import-and-export.md)
- [Search documentation and API specs](/search.md)