AI Tools & Scripts
API Change Report: What May Break for Your API Consumers, from Two Specs
For API teams and agencies: a script compares your old and new OpenAPI or Swagger file by fixed rules, and your agent drafts a report of potentially breaking changes, a migration guide, changelog entry and notice for integrators, for you to review. تقرير بما قد ينكسر عند مستخدمي الـ API بين نسختين.
What you get: 1 file · 76.62 KB · ZIP
See purchase optionsProduct description
English
For backend developers, API teams and agencies who ship a new version of an HTTP API and have to tell the people who call it what changed.
Give your agent the old and the new description of your API (OpenAPI 3.x or Swagger 2.0, JSON or YAML). The agent drafts a change report, a migration guide and a notice for integrators, for you to review before you publish.
The report lists potentially breaking changes found by comparing the two files. It is a starting point for your team's review, not a confirmed compatibility assessment.
A bundled script compares the two files and classifies every difference by fixed rules. The agent then writes what each change means for a client: what it will see, and what it has to change.
What the agent writes each run
changes.jsonandchanges.csv: every difference with an id, a class (breaking, potentially breaking, non-breaking, documentation only), its kind, the method and path, and the old and new value.change-report.mdandchange-report.html: the summary counts, then breaking changes first, each with where it is, what changed, what a client will see and what to change. The HTML is one printable page with no outside files.migration-guide.md: steps for the developers who call the API, with before and after snippets taken from the two files.changelog-entry.md: a changelog entry and a suggested version bump with the reasoning. The team decides.consumer-notice.md: a short, factual announcement for integrators.notes.md: what was compared, what a comparison of two files cannot show, and what needs a decision.
Rules, not guesses
The script knows 118 kinds of change in four classes, with separate rules for what a client sends and what it receives: a new required request field is breaking, a new response field is not. It follows local $refs. Run api_diff.py rules to read every rule. check then confirms that every breaking id is covered in the report and in the guide.
Your facts only
The skill instructs the agent to take snippets, paths and values from your two files, and to mark what you did not supply, such as a shutdown date for the old version, as [NEEDS: ...] instead of filling it in.
Honest about its limits
It compares two files. It does not call your API, so behaviour that the description does not state is outside its view. Classes come from rules and are for your team to confirm. Only local $refs are followed: a spec split over several files gives a warning and an incomplete comparison. The YAML reader covers the common subset and names the line when it meets something else (convert that file to JSON). Regex patterns and oneOf / anyOf are reported as changed without being evaluated. Response headers, links, callbacks and webhooks are not compared. With no spec the agent can compare a simple endpoint list it builds from your route files; that path is weaker and was not run end to end in testing. The HTML page was checked by reading its source, not in a browser.
Arabic
On request the report, the guide and the notice are written in Arabic and the HTML page is set right to left, with paths and JSON kept left to right.
In the download: SKILL.md, four standard-library Python scripts, references (the rules, how to write each entry, input formats, Arabic notes), templates, and a worked example you can read before you buy: a payments API going from 1.8.0 to 2.0.0, with 75 differences grouped into 11 breaking entries.
Tried on two cases (an OpenAPI 3 YAML payments API in English; a Swagger 2.0 JSON clinic API with an Arabic report). The scripts have 85 unit tests.
بالعربي
لمطوّري الواجهات الخلفية وفرق الـ API الذين يصدرون نسخة جديدة ويحتاجون أن يخبروا مستخدميها بما تغيّر.
أعطِ وكيلك ملف وصف النسخة القديمة وملف النسخة الجديدة (OpenAPI 3 أو Swagger 2، بصيغة JSON أو YAML). يكتب لك مسودة تقرير التغييرات ودليل الترحيل وإشعارًا للمطوّرين، لتراجعها قبل النشر.
ماذا يكتب الوكيل
- ملفا
changes.jsonوchanges.csv: كل فرق مع رقمه وتصنيفه ومكانه والقيمة القديمة والجديدة. - ملف
change-report: التغييرات الكاسرة أولًا، ومع كل تغيير ما الذي سيراه العميل وما الذي عليه تعديله. - ملف
migration-guide.md: خطوات الترحيل مع مقاطع قبل وبعد مأخوذة من ملفيك. - ملف
changelog-entry.mdوملفconsumer-notice.md: سجل التغييرات وإشعار قصير.
حدودها
النتائج تغييرات يُحتمل أن تكون كاسرة وتحتاج مراجعة فريقك. المهارة تقارن ملفين ولا تتصل بالـ API، فما لا يذكره الوصف لا تراه. التصنيف مبني على قواعد ثابتة ويؤكده فريقك. وتتبع المراجع داخل الملف نفسه فقط. ويمكن طلب التقرير بالعربية مع صفحة من اليمين إلى اليسار؛ جُرّب ذلك على حالة اختبار واحدة.
Questions / أسئلة
Which formats does it read? / أي صيغ يقرأ؟
OpenAPI 3.x and Swagger 2.0, in JSON or YAML. The YAML reader covers the common subset and names the line if it meets a feature it does not read; convert that file to JSON. يقرأ OpenAPI 3 و Swagger 2 بصيغة JSON أو YAML.
Does it call my API? / هل يتصل بالـ API؟
No. It compares two files on your disk. Behaviour that the description does not state is outside its view. لا، يقارن ملفين فقط.
How does it decide what is breaking? / كيف يحدد التغيير الكاسر؟
By fixed rules you can read with the rules command: 118 kinds of change in four classes, with separate rules for what a client sends and what it receives. Your team confirms the classes. بقواعد ثابتة تستطيع قراءتها.
What if my spec is split over several files? / ماذا لو كان الوصف في عدة ملفات؟
Only references inside the same file are followed. Bundle the spec into one file first; otherwise you get a warning and an incomplete comparison. ادمج الملفات في ملف واحد أولًا.
Will it invent a shutdown date? / هل يخترع موعد إيقاف النسخة القديمة؟
The skill instructs the agent not to. Dates and timelines you did not supply are marked [NEEDS: ...] for you to fill in. لا، يضع علامة لتكملها أنت.
Can the report be in Arabic? / هل يكون التقرير بالعربي؟
Yes, as an added option, with a right-to-left HTML page and paths kept left to right. It was tried on one test case; read it before publishing. نعم، مع صفحة من اليمين إلى اليسار.
What you get
1 file · 76.62 KB
- api-change-report-1.0.0.zipZIP · 76.62 KB
AI Tools & Scripts
API Change Report: What May Break for Your API Consumers, from Two Specs
For API teams and agencies: a script compares your old and new OpenAPI or Swagger file by fixed rules, and your agent drafts a report of potentially breaking changes, a migration guide, changelog entry and notice for integrators, for you to review. تقرير بما قد ينكسر عند مستخدمي الـ API بين نسختين.
Getly opened the uploaded files and found nothing that would stop them opening. It is not a virus scan or a quality rating.
Tags
Frequently asked questions
Do I get access instantly?
Yes. This is a digital product - you can download it right after checkout, straight from your library.
Can I use it for commercial projects?
Yes. Commercial use is allowed: use it in your own business and in things you sell. You may not resell or redistribute the file itself.
What's your refund policy?
You can request a refund within 30 days. If something isn't right, request it from your order and the Getly team reviews it.
What file formats and sizes will I get?
You'll download 1 file - ZIP - 76.62 KB in total.
Do I get free updates?
Yes - when the seller ships a new version, you can re-download the latest files from your library at no extra cost. Check the changelog for recent updates.
Price
$7.00



