Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Talk:Core APIs

From MoodleDocs

Some early comments about this list of APIs

  • Surely there is one reason for inventing this, completely bypassing the existing components (both for plugins, subplugins and subsystems). But I cannot really imagine it. Why not use direct mapping between components and APIs ? Code is going to use ones and docs are going to use another?
  • More yet, I don't get why the list of APIs ignores everything that is provided with plugin abilitites. Aren't "auth" or "enrol" or "reports" valid core APIs? In fact I think that the parts of Moodle currently working under the "plugins umbrella" are the most formal APIs we have in codebase (at least the OOP ones).
  • Some of the APIs in the list seem incorrect, inaccurate:
    • database API. it should be split, for sure in ddl and dml APIs at least.
    • time API. => datetime, surely.
    • renderer API => is that really an API
    • upgrade API => WTF is that? I'm specially interested on that, as far as it seems I'm the man in charge of documenting it and I don't know what the hell it is (MDL-30971).
    • grade and grading APIs => Should we have also group and grouping APIs? (sorry, joking, hehe, but don't buy the difference).
    • preference API : set/get/remove_user_preference() functions? Or also config ?
    • admin API ?
    • user API ?
    • install/uninstall API ?
    • ...
    • ...

So, in summary, I don't get which benefits this new list provides, nor I think we are doing well by keeping apart some APIs because of them being "pluggable", nor I think the APIs are well balanced at all. Just my 2cents (really not destructive, but constructive, although it sounds the opposite, guys).

--Eloy Lafuente (stronk7) 05:52, 5 January 2012 (WST)

Hi,

Certainly I agree with Eloy on this one. Why introduce another list of the same API's we already have.
While they look 80% the difference between the code and documentation will cause real confusion for developers learning Moodle, especially in regards to terminology.

I think we need to take great care that we don't come up with new terminology for things within Moodle.
As Eloy noted there are some things in the API list that don't make sense, I've just gone through as part of MDL-30979 and updated the PHP docs for the Output API's. I assume that is what you mean by renderer API, hehe you've confused me with that one?!

Cheers
--Sam Hemelryk 09:48, 5 January 2012 (WST)

i think i also generally share the sentiments above, so here's my general 'exactly!' for the above.

definitely for ddl and dml being mashed together into database API is sad loss of definition. I think theres certainly room for more planned and in depth discussions about our terminologies. not to mention the phpdoc is still not clearly and somewhat agreeably defined in our documentation project where we're implementing this atm.

(whee first talk page comment by me!) cheers!

Aparup Banerjee 00:18, 6 January 2012 (WST)



This new list is for documentation purposes only. We need a new list because NO OLD LIST OF APIS EXISTS! There *is* no table of contents that can group all the main functions available for *PLUGIN AUTHORS*. This started as a subset of get_core_subsystems() and has had things added where necessary.

Getting to specifics from above, based on discussion in HQ this morning and my thoughts:

  • database -> ddl and dml AGREED, done.
  • time -> datetime Is the reason because of PHPs name? We don't use that name anywhere else?
  • renderer -> output AGREED. Either is fine for me. "Renderer" was what EU people agreed on some weeks ago and it is a bit better for googling, but whatever.
  • upgrade API : It's meant to be everything you can do in upgrade/install (including upgradelib.php and all the tricks we use), and I was thinking it included DDL too. We can leave it until later if required.
  • grade and grading APIs => They are completely separate APIs. The names are a little confusing but I think we need to reuse get_core_subsystems() were possible.
  • preference API : set/get/remove_user_preference() functions, yes.
  • admin API -> Yes, I guess we need to explain settings.php and friends. Thanks.
  • user API -> That's hard to identify. I left it out for now as very few plugins needs to create/edit/delete users. or courses.
  • install/uninstall API -> Don't know about that. install.xml and what else?

--Martin Dougiamas 11:28, 6 January 2012 (WST)

Re: a User and a Course API, I think these would be very useful for those of us trying to integrate Moodle with our Student Information Systems. I had a look at Jerome's Web Services API, but I think there have been some fundamental oversights in that implementation. All of those functions require that you know the ID of things like users and courses, when an external system is not going to have that information. It would be useful to be able to do things like: 

  • $user = get_user(array('username'=>'chrisf'));

  • $course = get_course(array('idnumber'=>'CF101'));

  • enrol_user(array('username'=>'chrisf'), array('idnumber'=>'CF101') [,rolename])
    .

The user and course tables contain columns for 

idnumber

, which seems uniquely suited to operations of this type. I'm kind of surprised no-one else seems to be looking for this kind of API.

-- Chris Fryer 23:07, 20 February 2012 (WST)

About completion and availability (aka condition)

Plz, take a look to MDL-30996 (and MDL-30995). IMO we need to clearly state the differences and uses, both between those 2 APIs and with the "course completion" one, that I don't know if should have its own API. This involves rethinking the names given for each API, and their occurrences/explanation both in phpdocs and Docs.

--Eloy Lafuente (stronk7) 19:47, 8 February 2012 (WST)

I agree, we should state differences and uses between completion and condition. Saying so, condition should not be changed to availability, because get_core_subsystem() return condition and it should be similar. I am not sure about course_completion, so no comments.

--Rajesh Taneja (rajesh)

But, once again, we decided to have the APIs under the @category umbrella to have them *separated* (and free) from packages. So I don't find any problem naming them properly (and differently from their @package couterparts). They are just two *independent* ways to list/group things, so better if at least one of them is correct.
--Eloy Lafuente (stronk7) 17:19, 9 February 2012 (WST)

Some 2 little details about naming

  • Also, offtopic, it's a bit inconsistent to use "gerunds" for some APIs (rating, grading...), plurals for others (files..) and nouns/verbs (which is the official way, nouns?) for the rest.
  • Finally, Docs should match the name of the API completely, or at least offer one redirect from it, so anybody can make https://docs.moodle.org/dev/xxxx_API and arrive to the desired page. Sounds silly but surely it's useful to include jumps between system X and the Docs.

--Eloy Lafuente (stronk7) 19:58, 8 February 2012 (WST)

Retrieved from "https://docs.moodle.org/dev/index.php?title=Talk:Core_APIs&oldid=60080"
Powered by MediaWiki