khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-02 17:59:36 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #13450 from nextcloud/feat/dev/consumable-api

Browse Source 
feat(developer): Document Consumable vs. Implementable OCP
This commit is contained in:
Joas Schilling
2025-08-04 16:25:56 +02:00
committed by GitHub
parent 1c3cba2c25 155d4c217f
commit f7e7e5f5b2
2 changed files with 42 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst
View File

@@ -33,6 +33,24 @@ Removed APIs
Back-end changes
----------------
- OCP API split into consumable and implementable:
For a more informed background see `RFC: Split OCP into Consumable and Implementable <https://github.com/nextcloud/standards/issues/15>`_ for more information.
Short summary:
- **Consumable:** Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Consumable`` attribute, must only be consumed by apps and can not be implemented by apps themselves.
This means the server side can extend the interface with new methods or reduce returned types of existing methods without it being consider an API break.
However argument types of existing methods can **not** be reduced.
Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Listenable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Catchable`` attribute.
- **Implementable:** Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Implementable`` attribute, can be implemented by apps.
This means the server side can **not** extend the interface with new methods or reduce returned types of existing methods without it being consider an API break.
However argument types of existing methods can be reduced.
Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Dispatchable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Throwable`` attribute.
- **ExceptionalImplementable:** Despite not being implementable for all apps, some interfaces can have the ``OCP\AppFramework\Attribute\ExceptionalImplementable`` attribute indicating that they are implementable by a single app (or multiple).
In those cases the general ``OCP\AppFramework\Attribute\Consumable`` rules apply, but the app maintainers or repository of named exceptions have to be informed during the process of a pull request, leaving them enough time to align with the upcoming change.
- These new attributes will be applied on a "defacto standard" basis to the best of our knowledge.
In case an API was flagged unexpectedly, leave a comment on the respective pull request in the server repository asking for clarification.
Added APIs
^^^^^^^^^^

24
developer_manual/digging_deeper/api.rst
View File

@@ -8,6 +8,30 @@ PHP public API
The public API is contained in the OCP namespace. See the `OCP API reference
<https://nextcloud-server.netlify.app/>`_ for further details.
The API is split into two categories. Those are indicated by attributes.
``Consumable``, ``Listenable`` and ``Catchable``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Consumable`` attribute, must only be consumed by apps and can not be implemented by apps themselves.
This means the server side can extend the interface with new methods or reduce returned types of existing methods without it being consider an API break.
However argument types of existing methods can **not** be reduced.
Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Listenable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Catchable`` attribute.
``Implementable``, ``Dispatchable`` and ``Throwable``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Implementable`` attribute, can be implemented by apps.
This means the server side can **not** extend the interface with new methods or reduce returned types of existing methods without it being consider an API break.
However argument types of existing methods can be reduced.
Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Dispatchable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Throwable`` attribute.
``ExceptionalImplementable``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Despite not being implementable for all apps, some interfaces can have the ``OCP\AppFramework\Attribute\ExceptionalImplementable`` attribute indicating that they are implementable by a single app (or multiple).
In those cases the general ``OCP\AppFramework\Attribute\Consumable`` rules apply, but the app maintainers or repository of named exceptions have to be informed during the process of a pull request, leaving them enough time to align with the upcoming change.
PHP unstable API
----------------