How to create an endpoint

rloyola

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

rloyola

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

R_J

https://open.vanillaforums.com/discussion/comment/255495#Comment_255495

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

R_J

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

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?

charrondev

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

https://docs.vanillaforums.com/developer/apiv2/

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.

Aolee

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

R_J

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

charrondev

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.
  • Forum API endpoints.
  • Dashboard API endpoints.
• 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_J

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

charrondev

name:s is the correct version.

The schema is actually a separate library and documented here

https://github.com/vanilla/garden-schema/blob/master/README.md

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.