Skip to content

[Devportal] Fix several consistency issues in devportal REST APIs #2660

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

Merged
lasanthaS merged 8 commits into from
Jul 15, 2026
Merged

[Devportal] Fix several consistency issues in devportal REST APIs #2660

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d84d89c
Replace 'apiTitle' with 'title' for consistency
Piumal1999 Jul 14, 2026
5ddb39f
Fix inconsistencies in api and mcp rest apis
Piumal1999 Jul 14, 2026
be5919b
Correct the response/error body format
Piumal1999 Jul 14, 2026
258fd82
Generalize request body attributes for apis and mcps
Piumal1999 Jul 14, 2026
9538122
Update docs
Piumal1999 Jul 14, 2026
4ecadf0
Fix tests and address comments
Piumal1999 Jul 14, 2026
b10c58f
Update docs
Piumal1999 Jul 14, 2026
7ca59a1
Remove deprecated docs
Piumal1999 Jul 14, 2026
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
94 changes: 13 additions & 81 deletions docs/rest-apis/devportal/api-content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ curl -X POST https://localhost:3000/api/v0.9/apis/{apiId}/assets \

Uploads the static content package for an API.

The `apiContent` ZIP must contain at least one of these root directories:
The `content` ZIP must contain at least one of these root directories:
- `web/` for API landing-page assets such as markdown, HTML, CSS, JavaScript, and images.
- `docs/` for downloadable API documents.

Expand All @@ -31,7 +31,7 @@ Use `imageMetadata` to map uploaded images to API image roles such as the API ic
> Payload

```yaml
apiContent: string
content: string
docMetadata: '[{"name":"External
guide","url":"https://example.com/docs/guide","type":"LINK"}]'
imageMetadata: '{"api-icon":"icon.png"}'
Expand All @@ -50,7 +50,7 @@ This operation requires <strong>Basic Auth</strong> authentication.
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|body|body|object|true|API content ZIP upload.|
|» apiContent|body|string(binary)|true|ZIP upload field named `apiContent`.|
|» content|body|string(binary)|true|ZIP upload field named `content`.|
|» docMetadata|body|string|false|Optional JSON string containing API document link metadata.|
|» imageMetadata|body|string|false|Optional JSON string containing API image metadata.|
|apiId|path|string|true|The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.|
Expand All @@ -76,23 +76,7 @@ At least one of `web/` or `docs/` must exist at the ZIP root.
}
```

> Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.

```json
[
{
"status": "error",
"code": "COMMON_VALIDATION_ERROR",
"message": "Input validation failed.",
"errors": [
{
"field": "name",
"message": "name is required."
}
]
}
]
```
> Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.

```json
{
Expand Down Expand Up @@ -133,7 +117,7 @@ At least one of `web/` or `docs/` must exist at the ZIP root.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|JSON message response.|[MessageResponse](schemas.md#schemamessageresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.|Inline|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.|Inline|
|409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|The request conflicts with an existing resource.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

Expand All @@ -144,7 +128,6 @@ At least one of `web/` or `docs/` must exist at the ZIP root.
|Property|Value|
|---|---|
|status|error|
|status|error|

## Replace API content

Expand Down Expand Up @@ -174,7 +157,7 @@ Image metadata is updated only when image metadata can be resolved from the uplo
> Payload

```yaml
apiContent: string
content: string
docMetadata: '[{"name":"External
guide","url":"https://example.com/docs/guide","type":"LINK"}]'
imageMetadata: '{"api-icon":"icon.png"}'
Expand All @@ -193,7 +176,7 @@ This operation requires <strong>Basic Auth</strong> authentication.
|Name|In|Type|Required|Description|
|---|---|---|---|---|
|body|body|object|true|API content ZIP upload.|
|» apiContent|body|string(binary)|true|ZIP upload field named `apiContent`.|
|» content|body|string(binary)|true|ZIP upload field named `content`.|
|» docMetadata|body|string|false|Optional JSON string containing API document link metadata.|
|» imageMetadata|body|string|false|Optional JSON string containing API image metadata.|
|apiId|path|string|true|The API's handle (unique per org). Resolves only to REST/SOAP/WS/WebSub/GraphQL APIs — MCP servers are addressed via `/mcp-servers`.|
Expand All @@ -219,23 +202,7 @@ At least one of `web/` or `docs/` must exist at the ZIP root.
}
```

> Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.

```json
[
{
"status": "error",
"code": "COMMON_VALIDATION_ERROR",
"message": "Input validation failed.",
"errors": [
{
"field": "name",
"message": "name is required."
}
]
}
]
```
> Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.

```json
{
Expand Down Expand Up @@ -276,7 +243,7 @@ At least one of `web/` or `docs/` must exist at the ZIP root.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|JSON message response.|[MessageResponse](schemas.md#schemamessageresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.|Inline|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.|Inline|
|409|[Conflict](https://tools.ietf.org/html/rfc7231#section-6.5.8)|The request conflicts with an existing resource.|[ErrorResponse](schemas.md#schemaerrorresponse)|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

Expand All @@ -287,7 +254,6 @@ At least one of `web/` or `docs/` must exist at the ZIP root.
|Property|Value|
|---|---|
|status|error|
|status|error|

## Get an API content file

Expand Down Expand Up @@ -345,23 +311,7 @@ This operation requires <strong>Basic Auth</strong> authentication.
}
```

> Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.

```json
[
{
"status": "error",
"code": "COMMON_VALIDATION_ERROR",
"message": "Input validation failed.",
"errors": [
{
"field": "name",
"message": "name is required."
}
]
}
]
```
> Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.

```json
{
Expand Down Expand Up @@ -398,7 +348,7 @@ This operation requires <strong>Basic Auth</strong> authentication.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Stored API content asset. The concrete media type depends on the stored file extension or whether the content is an external document link.|string|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.|Inline|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.|Inline|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Plain text success response.|string|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

Expand All @@ -409,7 +359,6 @@ This operation requires <strong>Basic Auth</strong> authentication.
|Property|Value|
|---|---|
|status|error|
|status|error|

## Delete API content files

Expand Down Expand Up @@ -450,23 +399,7 @@ This operation requires <strong>Basic Auth</strong> authentication.

> Example responses

> Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.

```json
[
{
"status": "error",
"code": "COMMON_VALIDATION_ERROR",
"message": "Input validation failed.",
"errors": [
{
"field": "name",
"message": "name is required."
}
]
}
]
```
> Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.

```json
{
Expand Down Expand Up @@ -503,7 +436,7 @@ This operation requires <strong>Basic Auth</strong> authentication.
|Status|Meaning|Description|Schema|
|---|---|---|---|
|204|[No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5)|API content deleted successfully.|None|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Input validation failures are returned as an array; other bad request errors are returned as a standard error object.|Inline|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.|Inline|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Plain text success response.|string|
|500|[Internal Server Error](https://tools.ietf.org/html/rfc7231#section-6.6.1)|Internal server error.|[ErrorResponse](schemas.md#schemaerrorresponse)|

Expand All @@ -514,4 +447,3 @@ This operation requires <strong>Basic Auth</strong> authentication.
|Property|Value|
|---|---|
|status|error|
|status|error|
Loading
Loading