AEP Purpose and Guidelines
As Thryv’s API ecosystem grows, we need consistent documentation and design patterns to ensure our APIs are intuitive, reliable, and easy to use. AEPs provide a standardized way to document and share API design decisions across Thryv.
What is an AEP?
Section titled “What is an AEP?”AEP stands for API Enhancement Proposal, which is a design document providing high-level, concise documentation for API development.
Companies that adopt the AEP program use them as a source of truth for API-related documentation, and the means by which service producers discuss and come to consensus on API guidance. AEPs are maintained as Markdown files with metadata in the AEP GitHub repository.
Types of AEPs
Section titled “Types of AEPs”There are several different types of AEPs, described below. The list of AEP types may evolve over time as necessary.
Guidance
Section titled “Guidance”These AEPs describe guidance on API design. These are provided as instruction for API producers to help write simple, intuitive, and consistent APIs and are used by API reviewers as a basis for review comments.
Process
Section titled “Process”These AEPs describe a process surrounding API design. They often affect the AEP process itself and are used to enhance the way in which AEPs are handled.
Educational
Section titled “Educational”These AEPs provide the prerequisite knowledge and theoretical background for effective API design. They explain the “what” and “why” of industry-standard technologies (like HTTP or JSON) without necessarily imposing company-specific constraints.
Stakeholders
Section titled “Stakeholders”Editors
Section titled “Editors”The AEP editors are responsible for:
- Reviewing and approving AEPs
- Maintaining AEP quality and consistency
- Managing the AEP workflow and numbering
- Ensuring AEPs are clear, actionable, and well-written
Current editors are the members of the Gryffindor team.
States
Section titled “States”At any given time, AEPs may exist in a variety of states as they work their way through the process. The following is a summary of each state.
The initial state for an AEP is the “Draft” state. This means that the AEP is being discussed and iterated upon.
Reviewing
Section titled “Reviewing”The AEP has a solid proposal and is under formal review by the AEP maintainers. Changes may still be requested before approval.
Approved
Section titled “Approved”The AEP is approved and represents Thryv’s current best practice. This is the state you should follow for API design.
Withdrawn
Section titled “Withdrawn”If an AEP is withdrawn by the author or champion, it enters “withdrawn” state. AEPs that are withdrawn may be taken up by another champion.
Rejected
Section titled “Rejected”If an AEP is rejected by the AEP editors, it enters “rejected” state. AEPs that are rejected remain and provide documentation and reference to inform future discussions.
Replaced
Section titled “Replaced”The AEP has been superseded by a newer AEP with updated guidance.
Workflow
Section titled “Workflow”The following workflow describes the process for proposing an AEP, and moving an AEP from proposal to implementation to final acceptance.
Overview
Section titled “Overview”Proposing an AEP
Section titled “Proposing an AEP”Anyone at Thryv can propose a AEP!
In order to propose an AEP, first open a pull request with a draft AEP; the AEP should conform to the guidance in AEP-8. Most AEPs should be no more than two pages if printed out.
If the technical steering committee has suggested an AEP number, use that; otherwise use 9999 (and expect to change it during the course of the review).
In most circumstances, the committee will assign the proposal an AEP number and begin discussion. Once there is consensus, the committee will merge the PR, and the AEP will enter the “reviewing” state.
The committee may reject an AEP outright if they have an obvious reason to do so (e.g. the proposal was already discussed and rejected in another AEP or is fundamentally unsound), in which case the PR is not merged.
Accepting an AEP
Section titled “Accepting an AEP”The editors will work together to ensure that qualified proposals do not linger in review.
To gain final approval, an AEP must be approved by, at minimum, two members of the technical steering committee. Additionally, there should not be any committee members requesting significant changes (indicated by the use of the “changes requested” feature on GitHub).
Once the AEP is approved, the editors will update the state of the AEP to reflect this and submit the PR.
Withdrawing or Rejecting an AEP
Section titled “Withdrawing or Rejecting an AEP”The author of an AEP may decide, after further consideration, that an AEP should not advance. If so, the author may withdraw the AEP by updating the PR adding a notice of withdrawal with an explanation of the rationale.
Additionally, the author may be unable to get consensus among the group and the technical steering committee may elect to reject the AEP. In this situation, the committee shall amend the PR adding a notice of rejection with an explanation of the rationale. In both cases, the committee must update the state accordingly and submit the PR.
Replacing an AEP
Section titled “Replacing an AEP”In rare cases, it may be necessary to replace an AEP with another one. This is not general practice: minor edits to approved AEPs are acceptable and will be the common way to tweak guidance. However, if new guidance fundamentally alters the old guidance in some way, then the AEP editors shall create a new AEP that, once approved, will replace the old one. The old one then enters the “Replaced” state and will link to the new, current AEP.
Questions?
Section titled “Questions?”- Slack: #ask-pd-api
- Repository: GitHub Issues
Changelog
Section titled “Changelog”- 2026-01-20: Add educational AEP type.
- 2025-10-30: Initial AEP-1 for Thryv, adapted from Google AIP-1 and aep.dev AEP-1.