Users running a non-download version of Vanilla (pulled from github), on branch release/2019.016 or master from the last 2 weeks should upgrade to release/2019.017 or latest master for security reasons. Downloaded official open sources releases are not affected.

How to create an endpoint

Hi

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

Thanks

Comments

  • rloyolarloyola New
    edited October 14

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

  • R_JR_J Cheerleader & Troubleshooter Munich Moderator

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


    rloyola
  • R_JR_J Cheerleader & Troubleshooter Munich Moderator

    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


    rloyola
  • rloyolarloyola New
    edited October 14

    Instead of using   

    $sender->render(parent::getView('someview.php'));

    I use

      $sender->setData('loginToken',$token);

       $sender->renderData();

    is there a negative effects on using this?

  • charrondevcharrondev Application Developer (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.

    rloyolaAolee
  • AoleeAolee Hobbyist & Coder ✭✭

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

  • R_JR_J Cheerleader & Troubleshooter Munich Moderator

    @charrondev

    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.


    rloyola
  • charrondevcharrondev Application Developer (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.

    Takeway

    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.

  • R_JR_J Cheerleader & Troubleshooter Munich Moderator

    @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:

    <?php
    
    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.',
               ],
               'in'
           );
    
           $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?


  • charrondevcharrondev Application Developer (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.