feat: create api design best practices

[pengying]

No description provided.

[pengying]

• feat: adding umaaas mcp server #252
• feat: create api design best practices #251 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR introduces a new openapi/README.md intended as a living document for API design best practices. The document is explicitly framed as a work-in-progress, but several sections appear to be incomplete stubs rather than intentional placeholders.

• The ## Directory structure section is completely empty with no content.
• The ## Service Structure section contains only the text Prefer stuff, which appears to be an unfinished placeholder rather than real guidance.
• The Naming Conventions table has a malformed last row missing its closing pipe |, which will cause rendering issues in GitHub and other Markdown renderers.

Confidence Score: 4/5

Documentation-only change with no runtime impact; safe to merge but ships in an incomplete state.

The file introduces a guidelines document with two sections that contain no real content (one entirely empty, one with literal placeholder text) and a malformed Markdown table. Engineers pointed to this document for guidance would find it unhelpful or confusing.

openapi/README.md — all three sections need content before this document is useful as a reference.

Important Files Changed

Filename	Overview
openapi/README.md	New API design guidelines document added, but it is largely a stub — the Directory Structure section is empty, the Service Structure section contains placeholder text ("Prefer stuff"), and the Naming Conventions table has a malformed row missing a closing pipe.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[openapi/README.md] --> B[API Design Guidelines]
    B --> C[Directory Structure]
    B --> D[Naming Conventions]
    B --> E[Service Structure]
    C --> C1["⚠️ Empty — no content"]
    D --> D1[Common Fields Table]
    D1 --> D2["⚠️ Malformed row — missing closing pipe"]
    E --> E1["⚠️ Placeholder — 'Prefer stuff'"]

Loading

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
openapi/README.md:15
The last row of the Markdown table is missing a closing pipe `|`. Without it, many Markdown renderers (GitHub, Mintlify, etc.) will either skip rendering the row or misformat the table entirely.

```suggestion
| timestamp | timestamp an event occurred |
```

### Issue 2 of 2
openapi/README.md:17-18
**Placeholder text left in document**

The `## Service Structure` section contains only `Prefer stuff`, which reads as an unfinished placeholder. If this document is intended to be merged and referenced by engineers writing new APIs, shipping it with placeholder content may cause confusion or be followed literally. The `## Directory structure` section (lines 8–10) is also empty with no content at all.

_{Reviews (1): Last reviewed commit: "feat: create api design best practices" | Re-trigger Greptile}

[greptile-apps]

The last row of the Markdown table is missing a closing pipe |. Without it, many Markdown renderers (GitHub, Mintlify, etc.) will either skip rendering the row or misformat the table entirely.

Suggested change

	| timestamp | timestamp an event occurred
	| timestamp | timestamp an event occurred |

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/README.md
Line: 15

Comment:
The last row of the Markdown table is missing a closing pipe `|`. Without it, many Markdown renderers (GitHub, Mintlify, etc.) will either skip rendering the row or misformat the table entirely.

```suggestion
| timestamp | timestamp an event occurred |
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Placeholder text left in document

The ## Service Structure section contains only Prefer stuff, which reads as an unfinished placeholder. If this document is intended to be merged and referenced by engineers writing new APIs, shipping it with placeholder content may cause confusion or be followed literally. The ## Directory structure section (lines 8–10) is also empty with no content at all.

Prompt To Fix With AI

This is a comment left during a code review.
Path: openapi/README.md
Line: 17-18

Comment:
**Placeholder text left in document**

The `## Service Structure` section contains only `Prefer stuff`, which reads as an unfinished placeholder. If this document is intended to be merged and referenced by engineers writing new APIs, shipping it with placeholder content may cause confusion or be followed literally. The `## Directory structure` section (lines 8–10) is also empty with no content at all.

How can I resolve this? If you propose a fix, please make it concise.