HackerOne users: Testing against this community violates our program's Terms of Service and will result in your bounty being denied.

How to create an endpoint


I have a thirdparty application that requires custom API URL that will return a login token

Is there a way to render a data, I want to return this when this url is accessed https://somsite.com/auth_token

  "loginToken": "already-saved-or-returned-login-token"

What is the best way to do this



  • Options
    rloyolarloyola New
    edited October 2019

    I also want to set the status code, is there an existing functionality in the framework that will allow this?

  • Options
    R_JR_J Ex-Fanboy Munich Admin

    Both answers can be found in the GitHub repo linked in this comment

  • Options
    R_JR_J Ex-Fanboy Munich Admin

    There is a section in the official docs which gives more information about creating your own end points: https://docs.vanillaforums.com/developer/addons/events-and-handlers/#magic-methods

  • Options
    rloyolarloyola New
    edited October 2019

    Instead of using   


    I use



    is there a negative effects on using this?

  • Options
    charrondevcharrondev Developer Lead (PHP, JS) Montreal Vanilla Staff

    @rloyola @R_J I would recommend using a custom APIv2 for any endpoints in the future.

    We have pretty good documentation and have been using this for everything for the past few years. This way you can have an actual controller to make your endpoints.

  • Options
    AoleeAolee Hobbyist & Coder ✭✭

    argh! I didnt see this one, created an end point url via plugin, similar to what the Whosonline plugin is doing.

  • Options
    R_JR_J Ex-Fanboy Munich Admin


    When I had a look at the API I came across a question that hasn't been answered then. I would still be interested in the question, though.

    Let's assume I would like to create a fancy catalogue page for tags (whatever that might be), I would start by writing a public function tagsController_catalogue_create() { which would show my page. But what would I have to do to make that info available as /api/v2/tags/catalogue?

    By the way: it took me quite some time to set up a simple ApiController for testing. A full blown example in the docs would be helpful.

  • Options
    charrondevcharrondev Developer Lead (PHP, JS) Montreal Vanilla Staff

    The process normally goes like this:

    • Create the API controller first. Do this by naming it MyNameApiController and extending AbstractApiController.
    • Make your endpoint. Check the docs or any of the endpoints we have available in the core repo. They can normally be found in the controllers/Api directory of any addon/application.
    • Document your endpoint with some yml files in the openapi directory. These are now written in yml, rather than PHP due to numerous bugs in our PHP -> openapi conversion that were happening before. Now the definitions can be written and edited directly with some live visual preview in your IDE.
    • Create you page that the user will land on. You can dependency inject your API controller and re-use it's logic here (prevent needing to duplicate). Don't forget to catch/rethrow exceptions of the proper type though.

    Tacking on a new endpoint to existing group through a plugin is really not recommended for a couple reasons.

    • The name you choose could clash with future endpoints in our product. For example in your linked thread you suggested /api/v2/users/signin. That is a very obvious name that me way want to use in the product in the future.
    • Things get more complicated from a coding perspective.

    If you do want an example, take a look at how Q&A adds fields & endpoints to discussions.


    We should probably update these docs. There's a documentation migration underway (help docs are already moved).

    I'm expecting more contribution to the developer docs once they are moved here into our knowledge base product & are more easy to search/contribute to.

  • Options
    R_JR_J Ex-Fanboy Munich Admin

    @charrondev When doing my tests I was looking at Vanillas API. Therefore I also stumbled upon the Schema class, which is a great helper but also sparsly documented. My simple test has been ended with this code:

    use Garden\Schema\Schema;
    use Garden\Web\Data;
    class AahApiController extends AbstractApiController {
       public function index(array $query) {
           return new Data([
               'File' => __FILE__,
               'Code Line' => __LINE__
       public function post(array $data) {
           $in = $this->schema(
                   'id:i' => 'Some numerical ID. Required.',
                   'name:s|n' => 'Some name. Optional because either string or null.',
           $result = $in->validate($data);
           return new Data($result);

    Could it be that the example in the schema documentation is wrong? s:name instead of name:s?

  • Options
    charrondevcharrondev Developer Lead (PHP, JS) Montreal Vanilla Staff

    name:s is the correct version.

    The schema is actually a separate library and documented here

    This is definitely an example of us just not documenting well enough. That should definitely be linked to. It's pretty useful even outside of APIs. For example, I've used it extensively for validation of input in our new embeds system.

Sign In or Register to comment.