Comment créer une API pour mon plugin?

L'API que vousproposez dans unplugin ou unthème dépend de la logique de ce code spécifique. Iln'y aprobablementpas deguide qui s'applique àtoutes les situations.

Je contribue àplusieursplugins avec des API,et ce quej'ai apprisjusqu'àprésentest:

1. Neproposezpas d'APItant que vousne savezpas vraiment comment lesgens utilisent votre code.

   Publiez les deux outroispremières versions sans aucune API. Pas d'actions ou defiltrespersonnalisés,pas deméthodes oufonctionspubliques (etjamais de variablesglobales) sipossible. Attendez les demandes de vos utilisateurs,maisn'ajoutezpas le codetant que vousne savezpas que votre structure de codeinternefonctionnera à longterme.

   Ilest difficile demaintenir la rétrocompatibilité d'une API . Celapourraitempêcher des améliorationsnécessaires à d'autresendroits. Pensez àtoutes les variablesglobales que WordPressne peutpas supprimer denosjours. C'est unemauvaise API,et nous y sommesbloqués depuis denombreuses années,car lesgens l'utilisent déjà .

2. Pensez à séparer votre API du reste du code (voir le lienprécédentpour uneidée).
   Votre API devrait être utilenon seulementpour les développeurstiers,mais aussipour vous. N'ajoutezpas de restrictionpour vous-même si vousn'êtespas obligé.

3. Mangez votreproprenourriturepour chien.
   Si vousproposez des hookspersonnalisés,utilisez-les dans votre code. Cela donnera à d'autres développeurs desexemples utiles,et vouspourrez voir lesfaillespossibles asseztôt.
   Si le cœur de WordPress utilisait la soi-disant API desparamètres en interne,nousn'aurionspas ce désordre aujourd'hui. Peut-être.

4. Donnez l'exemple.
   Utilisez lesbonnesparties de l'APIprincipale de WordPress dans votreplugin. Évitez les objets anonymes ,les constantes,les variablesglobaleset touttype de codeimprévisible .

5. Assurez-vous que vous utilisez un schéma de dénomination cohérent (etnon untel désordre ),et metteztout sous votrepropreespace denoms.

6. Rédigez d'abord la documentation. Publiez unenouvelle (partie d'une) APIplustard.
   Créez desexemples utilespourtout. Vous serez étonné de voir lenombre detrouset de redondances que voustrouverez.

7. Évitez l'enfer des rappels.
   Proposez des outils spécifiquespour déboguer votre API lorsque les chosesne fonctionnentpas commeprévu (y compris les scriptset lesfeuilles de stylenonminifiés) J'ai écrit unexemplepour savoir comment déboguer AJAX ,justepourillustrer à quelpoint vouspouvez être créatifici. Encore unefois,ces outils doivent êtreexpliqués dans votre documentation avant de lespublier.

8. Une alternative auparadigme de rappel de WordPresspourrait être le modèle d'observateur . Cela soulèverait labarrièrepour les développeurstiers,mais celapourraitentraîner unmeilleur code des deux côtés.

The API you offer in a plugin or a theme depends on the logic of that specific code. There is probably no guide that applies to all situations.

I am a contributor for multiple plugins with APIs, and what I have learned so far is:

1. Do not offer an API until you really know how people use your code.

   Release the first two or three versions without any API. No custom actions or filters, no public methods or functions (and never any global variables) if possible. Wait for requests from your users, but don’t add the code until you know your inner code structure will work in the long run.

   Maintaining backwards compatibility of an API is hard. It might prevent necessary improvements on other places. Think about all the global variables WordPress cannot remove nowadays. That’s a bad API, and we are stuck with it for many years, because people use it already.

2. Consider separating your API from the rest of the code (see previous link for an idea).
   Your API should be useful not only for third party developers, but for you too. Do not add restriction for yourself if you don’t have to.

3. Eat your own dog food.
   If you offer custom hooks, use them in your code. This will give other developers useful examples, and you can see possible flaws soon enough.
   If the WordPress core would use the so-called Settings API internally, we wouldn’t have this mess today. Maybe.

4. Lead by example.
   Use the good parts of the WordPress core API in your plugin. Avoid anonymous objects, constants, global variables and any kind of unpredictable code.

5. Make sure you are using a consistent naming scheme (not such a mess), and put everything under your own namespace.

6. Write the documentation first. Release a new (part of an) API later.
   Create useful examples for everything. You will be amazed to see how many holes and redundancies you will find.

7. Avoid callback hell.
   Offer specific tools to debug your API when things don’t work as they should (including not minified scripts and stylesheets). I have written an example for how to debug AJAX, just to illustrate how creative you can be here. Again, these tools should be explained in your documentation before you release them.

8. An alternative to WordPress’ callback paradigma could be the Observer pattern. This would raise the barrier for third-party developers, but it could result in better code on both sides.