Azure / Azure/typespec-azure

Provide a mechanism to manage private APIs after TypeSpec conversion

Open
#3,117 7 comments 0 reactions 0 assignees View on GitHub
design:needed eng
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

### Clear and concise description of the problem

While working with MySQL team on their TypeSpec conversion, service team has asked how to make private APIs and public APIs co-exist in TypeSpec because they have some private APIs that they don't want to expose to their external customers.

**Requirements**

- The private APIs is a set of valid server APIs for their internal usage. If service team uses server codegen, those APIs need to be generated with the corresponding controllers along side with public APIs.
- For all client emitters (SDKs and autorest and other emitters), to include private APIs when they are doing internal tests, but exclude those APIs when they are published.
- It's possible that those private APIs could be expose to the public customers someday.

**Questions**

- Should those private APIs go through the review if service team only wants to maintain one copy of their service TypeSpec in public specs repo main branch?
- If they should not put their private APIs in public main, where is the final place to host those private APIs TypeSpec for non-rpaas services?
- Is it possible have an independent TypeSpec project for private APIs but to load both the private TypeSpec with public TypeSpec with one tsp compile?
- If we have to mixed the private APIs with public APIs regardless of where they should be hosted, can TypeSpec team provide a decorator to achieve the **requirements**

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/azure/typespec-azure/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that this issue is about the Azure libraries for typespec. For feature request in the typespec language or core libraries file it in the [TypeSpec repo](https://github.com/Microsoft/TypeSpec/issues/new/choose)
- [x] Read the [docs](https://azure.github.io/typespec-azure/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

Contributor guide

Open the contributing guide

Research direction

No file, test, or entry point is named. Start by tracing how the TypeSpec conversion handles server code generation and client emitters, then review the requirements and open questions to determine the expected scope. Done would require an agreed mechanism and documented behavior for private APIs, rather than an isolated edit.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.