Skip to content

Commit 95ed479

Browse files
kosabogishainaraskasleemthompo
authored
Adds Serverless API examples page (elastic#2208)
As per this [issue](elastic#1280), the content of the Serverless API examples page was lost during the migration. This PR restores that content under the Elastic Cloud Serverless section. There is a related PR that adds a link to the newly added Serverless API example page in the API reference: elastic/serverless-api-specification#43 --------- Co-authored-by: shainaraskas <[email protected]> Co-authored-by: Liam Thompson <[email protected]>
1 parent c5c4aeb commit 95ed479

File tree

2 files changed

+150
-0
lines changed

2 files changed

+150
-0
lines changed

‎deploy-manage/deploy/elastic-cloud/manage-serverless-projects-using-api.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
mapped_pages:
3+
- https://www.elastic.co/guide/en/serverless/current/security-project-settings.html
4+
applies_to:
5+
serverless: ga
6+
navigation_title: Manage projects with API
7+
---
8+
9+
# Manage serverless projects using the API [serverless-api]
10+
11+
On this page, you can find examples of how to create and manage serverless projects using the [Elastic Cloud Serverless API](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/).
12+
13+
To learn about API principles, authentication, and how to use the OpenAPI specification, refer to the [Elastic Cloud Serverless API](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/) documentation.
14+
15+
The available APIs are grouped by project type:
16+
17+
- APIs for [Search projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-elasticsearch-projects)
18+
- APIs for [Observatibility projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-observability-projects)
19+
- APIs for [Security projects](https://www.elastic.co/docs/api/doc/elastic-cloud-serverless/group/endpoint-security-projects)
20+
21+
To try the examples in this section, [set up an API key](#general-manage-project-with-api-set-up-api-key) and [create an {{serverless-full}} project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project).
22+
23+
## Set up an API key [general-manage-project-with-api-set-up-api-key]
24+
25+
1. [Create an API key](https://www.elastic.co/docs/deploy-manage/api-keys/elastic-cloud-api-keys).
26+
2. Store the generated API key as an environment variable so that you don’t need to specify it again for each request:
27+
28+
```console
29+
export API_KEY="YOUR_GENERATED_API_KEY"
30+
```
31+
32+
## Create an {{serverless-full}} project [general-manage-project-with-api-create-a-serverless-elasticsearch-project]
33+
34+
```bash
35+
curl -H "Authorization: ApiKey $API_KEY" \
36+
-H "Content-Type: application/json" \
37+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch" \
38+
-XPOST --data '{
39+
"name": "My project", <1>
40+
"region_id": "aws-us-east-1" <2>
41+
}'
42+
```
43+
1. Replace `My project` with a more descriptive name in this call.
44+
2. You can obtain a [list of available regions](#general-manage-project-with-api-list-available-regions).
45+
46+
The response from the create project request will include the created project details, such as the project ID, the credentials to access the project, and the endpoints to access different apps such as {{es}} and {{kib}}.
47+
48+
Example of `Create project` response:
49+
50+
```console-response
51+
{
52+
"id": "cace8e65457043698ed3d99da2f053f6",
53+
"endpoints": {
54+
"elasticsearch": "https://sample-project-c990cb.es.us-east-1.aws.elastic.cloud",
55+
"kibana": "https://sample-project-c990cb-c990cb.kb.us-east-1.aws.elastic.cloud"
56+
},
57+
"credentials": {
58+
"username": "admin",
59+
"password": "abcd12345"
60+
}
61+
(...)
62+
}
63+
```
64+
65+
You can store the project ID as an environment variable for the next requests:
66+
67+
```console
68+
export PROJECT_ID=cace8e65457043698ed3d99da2f053f6
69+
```
70+
71+
## API examples
72+
73+
The following examples show how to interact with the APIs, covering common operations such as:
74+
75+
- [Creating a project](#general-manage-project-with-api-create-a-serverless-elasticsearch-project)
76+
- [Retrieving project details](#general-manage-project-with-api-get-project)
77+
- [Retrieving the project's status](#general-manage-project-with-api-get-project-status)
78+
- [Resetting credentials](#general-manage-project-with-api-reset-credentials)
79+
- [Deleting a project](#general-manage-project-with-api-delete-project)
80+
- [Updating a project](#general-manage-project-with-api-update-project)
81+
- [Listing regions where projects can be created](#general-manage-project-with-api-list-available-regions)
82+
83+
### Get project details [general-manage-project-with-api-get-project]
84+
85+
You can retrieve your project details through an API call:
86+
87+
```bash
88+
curl -H "Authorization: ApiKey $API_KEY" \
89+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}"
90+
```
91+
92+
### Get the project status [general-manage-project-with-api-get-project-status]
93+
94+
The 'status' endpoint indicates whether the project is initialized and ready to be used. In the response, the project's `phase` will change from "initializing" to "initialized" when it is ready:
95+
96+
```bash
97+
curl -H "Authorization: ApiKey $API_KEY" \
98+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/status"
99+
```
100+
101+
Example response:
102+
103+
```console-response
104+
{
105+
"phase":"initializing"
106+
}
107+
```
108+
109+
### Reset credentials [general-manage-project-with-api-reset-credentials]
110+
111+
If you lose the credentials provided at the time of the project creation, you can reset the credentials by using the following endpoint:
112+
113+
```bash
114+
curl -H "Authorization: ApiKey $API_KEY" \
115+
-XPOST \
116+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}/_reset-credentials"
117+
```
118+
119+
### Delete a project [general-manage-project-with-api-delete-project]
120+
121+
You can delete your project via the API:
122+
123+
```bash
124+
curl -XDELETE -H "Authorization: ApiKey $API_KEY" \
125+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}"
126+
```
127+
128+
### Update a project [general-manage-project-with-api-update-project]
129+
130+
You can update your project using a PATCH request. Only the fields included in the body of the request will be updated.
131+
132+
```bash
133+
curl -H "Authorization: ApiKey $API_KEY" \
134+
-H "Content-Type: application/json" \
135+
"https://api.elastic-cloud.com/api/v1/serverless/projects/elasticsearch/${PROJECT_ID}" \
136+
-XPATCH --data '{
137+
"name": "new name",
138+
"alias": "new-project-alias"
139+
}'
140+
```
141+
142+
### List available regions [general-manage-project-with-api-list-available-regions]
143+
144+
You can obtain the list of regions where projects can be created using the API:
145+
146+
```bash
147+
curl -H "Authorization: ApiKey $API_KEY" \
148+
"https://api.elastic-cloud.com/api/v1/serverless/regions"
149+
```

‎deploy-manage/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ toc:
3333
- file: deploy/elastic-cloud/create-serverless-project.md
3434
- file: deploy/elastic-cloud/regions.md
3535
- file: deploy/elastic-cloud/project-settings.md
36+
- file: deploy/elastic-cloud/manage-serverless-projects-using-api.md
3637
- file: deploy/elastic-cloud/cloud-hosted.md
3738
children:
3839
- file: deploy/elastic-cloud/create-an-elastic-cloud-hosted-deployment.md

0 commit comments

Comments
 (0)