Extend rest api

General discussion about MantisBT Plugins

Moderators: Developer, Contributor

Post Reply
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Extend rest api

Post by federico »

Hello.

I would like to extend the mantisbt rest api to implement new functions (not to build something new, and it should not be necessary if the api were complete). I tried the following approaches, but none of them seems to be satisfactory for me:
  • Copy the whole rest api infrastructure to my plugin and change it to make it work: it works, but I don't like it because complicates future manteinance and compatibility
  • Change the api/rest implementation: it works too, but also complicates future manteinance and compatibility
  • Create the spected results manually using the mantisbt api: reinventing the wheel
As everyone can see, none of them are good ideas. I am not fluent with PHP, but I know the http request lifecycle, and I worked successfully on rest services development with other technologies,

¿What are the best practices to extend the existing API in a friendly way? I haven't found any documentation about this in the developers guide.

Thank you in advance.
atrol
Site Admin
Posts: 8366
Joined: 26 Mar 2008, 21:37
Location: Germany

Re: Extend rest api

Post by atrol »

I have hardly any time at the moment to support such kind of questions.
You can try our Gitter channel where other devs are listening https://gitter.im/mantisbt/mantisbt

The best way to extend Mantis is to send a Pull Request on GitHub.
As an example check https://github.com/mantisbt/mantisbt/pull/1487/files (still in discussion)
https://github.com/mantisbt/mantisbt/pull/1453/files (implemented since version 2.20.0) https://www.mantisbt.org/bugs/view.php?id=25400
Please use Search before posting and read the Manual
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Re: Extend rest api

Post by federico »

Thank you atrol.

I saw the author of the rest api uses to participate in this forum, so I suposed he could explain the best practices to extend his own implementation into a plugin to keep things clear. I do not understand all the complexity behind this, because with other technologies it is quite simple, and you can choose into a wide range of solutions.

I am having an accelerate PHP course, and it reminds me the old times with ASP (before 2000), and why I decided to abandon developing with such technologies, and preferred real OO programming languages.
Starbuck
Posts: 219
Joined: 14 Feb 2006, 02:53
Location: USA
Contact:

Re: Extend rest api

Post by Starbuck »

@federico - Let's be specific. What would you like to add to the API? Maybe we can clone and adapt code, then submit a GH PR.

As to OO, PHP is now pretty good with OO. I suggest you look for existing code and model after the good examples.
If you want Mantis to work differently, use or create a plugin. Visit the Plugins forums.
Ask developers to create a plugin that you need - and motivate them to help you!
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Re: Extend rest api

Post by federico »

Thank you Starbuck.

I would like to know the good practices to get a new REST api function published in the mantis plugin context, reusing the mantis API REST core infrastructure. It could be a new service (based on my custom schema), or reusing an existing core api function to incorporate to my plugin an existing one (ie. as an AJAX call). I am not sure, but mantis REST API and SOAP API implementations, seems to be a subset of methods which narrows the core api, using a different infrastructure on each case.

I do not know how to import the current REST API infrastructure to create new REST services in the plugin architecture. I tried to create new services by creating and configuring these in the core code, and it works, but I do not want to follow that path.

In Java, or .NET, I use to get whatever I want to be published from my business layer as a JSON or SOAP service, just specifying attributes to methods, which includes protocol and security considerations. Alternatively, I can also use frameworks like spring, which allows me to publish whatever business layer method as a service (SOAP or REST) with a few XML configuration lines. When I start the development of a new project, I do not use to have complete information about future publishing requirements, and this kind of implementation, allows me to decide it later, in a scalable and simple way, and respecting existing business transactionality with independency of the client consuming the service.

The best solution I found, is to create in my plugin files folder, REST service pages, and: add the mantis context security considerations, receive the function to be invoked as a parameter (to be processed at the beginning of the request), the form data to be processed, and response with the right JSON result, but I do not like it either and seems to be botched.
Starbuck
Posts: 219
Joined: 14 Feb 2006, 02:53
Location: USA
Contact:

Re: Extend rest api

Post by Starbuck »

I hear ya. My main work is with C# and Java too, so I stutter a bit when I get into PHP. I also did ASP in the 90's so we're on the same page.

You'll notice that while I helped to create and administer this plugin section, I don't post code, for lack of expertise with PHP and lack of knowledge of this specific application. HOWEVER, my goal is to help facilitate plugin development, and that's what you're trying to do...

I will discourage citing PHP as the nature of any problems. It's a very capable language, better than perl, but ultimately might get usurped by JavaScript via NodeJS or possibly Python. For our purposes let's assume and agree that we can do anything with PHP with enough knowledge of this application for What we want to do, and some code viewing for How to do it.

To the challenge : One must first understand that the SOAP web service implementation for MantisBT is the most complete, but as we know SOAP is a somewhat deprecated protocol. REST is not as complete, but it is the way to the future. So there are features that are in SOAP, not REST. My quick summary of what we want to do here, and please correct me if this is wrong, is that we want to find a function that's available in SOAP, check to make sure it's not in REST yet, and then port it to REST.

To do that, we need to get more familiar with how other functions are implemented in REST. Find a function that's implemented in both protocols and see how they're doing it. Find another function and see the commonalities. We need to get that pattern into our heads, then apply that to a new REST function.

We need to ensure that we're following the routing/pathing that has been envisioned by other developers contributing to the REST implementation. That means getting into Gitter and opening a discussion with vboctor and dregad.

Federico, are you @FSD-Christian-ISS in Gitter?
Was that you asking recently about POST via REST?
Did you get any helpful info from the REST API docs?

Is all of this going down the right path?
Good luck!
If you want Mantis to work differently, use or create a plugin. Visit the Plugins forums.
Ask developers to create a plugin that you need - and motivate them to help you!
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Re: Extend rest api

Post by federico »

Thank you for your generous reply.

Building a plugin, is exactly what I am doing.

I started with mantis from the understanding of its architecture, and now, I have a well organized plugin working, using all its native components (schema, events, apis, pages, files, configuration, menus...), configuring the business view I need for a set of predefined manteinance services (called "projects" in mantis), matching my business requirements. It has been a pleasure to learn how mantis is done, to reach its high flexibility, reliability, and scalability (I've developed some state machines in the past, and the mantis solves most of the issues in an elegant way), but I am still a bit confused, because PHP not seems as a complete OO programming language implementation, and/or, mantis is not completely developed in that way.

Fortunately: mantis is enough flexible to match all my business requirements; PHP has an infinite development network; and the mantis documentation is complete, very well formed, and the product has a good support. It's greatness synthesizing complexity, has the reasonable price of adapting the business view to mantis paradigms (new business entities, or simply its structure...), which requires an integration solution, where plugin architecture also seems as a great option. This is something usual with software integrators, developing vertical (industry specialized) solutions, which now is the role I have, and the view I have applied to mantis, to decide if it is the core system that my customer needs to control some of its business services.

I am quite sure I am not making a mistake with my decission, and I feel conscient, and assuming the dificulty behind the result I am expecting. The new mantisbt UI, improves the user experience, but when you try to mix information from more than one system, and execute transactions to keep mantis working properly (i.e. user manteinance, where users could come from different data sources), some standard integration patterns and good practices are missed. Http and JSON are good standards for me, but I would like to make public the complete set of my plugin functions (the API section), and I would like to handle mantis business classes definitions and data structures to extend what I need (new business classes consuming new business services). I would like to extend the architecture applied to develop the existing JSON API, but I do not know the impact on the context. Simply, I would like to publish a JSON service

I need to know how to create in my plugin, new custom JSON services to manage my own business entities, integrated whith the mantis ensuring access level, and I would like to re-use the current mantis infrastructure. How?

This need is closely related with the mantis ability to manage groups of users, and could be easyly avoided with such capability, and that is why I have to develop something to paste both worlds. By now, I found three options: a) implement user groups, feeling as capable as mantis core develompent team, to modify the standard behaviour of the security for the whole system (I do not think so); b) wait to mantis team to develop such ability (100% business lost), and c), try to paste both worlds with a consistent process (may be, I will find a reasonable solution which could be performed with my notepad++ code editor and my phpMyAdmin as precarious tools).
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Re: Extend rest api

Post by federico »

I would like to share this small piece of code, which offers two benefits:
  • Integrate external data sources in the business layer
  • Retrieve JSON info which makes the UI more simple and accurate to work with data asynchronously
Is my first time with PHP and also Mantis, and I am not absolutely sure if things are right. It works for me, seems simple, and is as secure as mantisbt. It only works in mantis context, and no routing capabilities nor function invocation are developed yet (I do not know how, and thats is why I asked for re-use the existing mantis development).

Code: Select all

<?php

# service access level 
auth_ensure_user_authenticated();
auth_reauthenticate();
access_ensure_global_level( plugin_config_get( 'manage_academic_threshold' ) );
	
# clear the response output
ob_clean();	

$t_biz_users = new academic_users();

$t_users_data =  json_encode( $t_biz_users -> getRemoteUsers() );

# response headers
header( "Content-type:application/json;charset=utf-8" );
header( "Content-length:" . strlen( $t_users_data ) );

echo $t_users_data;

flush();

?>
HarryGreathouse
Posts: 1
Joined: 23 Jul 2019, 10:17

Re: Extend rest api

Post by HarryGreathouse »

federico wrote: 19 May 2019, 07:53 Thank you Starbuck.

I would like to know the good practices to get a new REST api function published in the mantis plugin context, reusing the mantis API REST core infrastructure. It could be a new service (based on my custom schema), or reusing an existing core api function to incorporate to my plugin an existing one (ie. as an AJAX call). I am not sure, but mantis REST API and SOAP API implementations, seems to be a subset of methods which narrows the core api, using a different infrastructure on each case.

I do not know how to import the current REST API infrastructure to create new REST services in the plugin architecture. I tried to create new services by creating and configuring these in the core code, and it works, but I do not want to follow that path.

In Java, or .NET, I use to get whatever I want to be published from my business layer as a JSON or SOAP service, just specifying attributes to methods, which includes protocol and security considerations. Alternatively, I can also use frameworks like spring, which allows me to publish whatever business layer method as a service (SOAP or REST) with a few XML configuration lines. Also, I wrote about this at https://edubirdie.com/thesis-editing-service. When I start the development of a new project, I do not use to have complete information about future publishing requirements, and this kind of implementation, allows me to decide it later, in a scalable and simple way, and respecting existing business transactionality with independency of the client consuming the service.

The best solution I found, is to create in my plugin files folder, REST service pages, and: add the mantis context security considerations, receive the function to be invoked as a parameter (to be processed at the beginning of the request), the form data to be processed, and response with the right JSON result, but I do not like it either and seems to be botched.
Oh, that's helpful. Thanks!
dregad
Developer
Posts: 75
Joined: 26 Jul 2010, 14:24

Re: Extend rest api

Post by dregad »

As an example of extending the REST API from a plugin, you can have a look at the Announce plugin.

You need to Then you can enjoy calling your API, e.g. https://github.com/mantisbt-plugins/Ann ... nce.js#L15

Hope this helps.
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Re: Extend rest api

Post by federico »

Thank you very much !
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Re: Extend rest api

Post by federico »

dregad wrote: 28 Aug 2019, 15:58 As an example of extending the REST API from a plugin, you can have a look at the Announce plugin.

You need to Then you can enjoy calling your API, e.g. https://github.com/mantisbt-plugins/Ann ... nce.js#L15

Hope this helps.
This works fine with my own service when I am already authenticated, but I need to invoke the service from a cron task,

I created the token with the admin user, and I try to execute the following code to test in the mantis application domain with no success:

Code: Select all

<!DOCTYPE html>

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta charset="utf-8" />
    
    <title></title>
</head>
<body>
    <script src="https://code.jquery.com/jquery-3.4.1.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
    <script type="text/javascript">
        var form = new FormData();
        var settings = {
            "url": "https://MYFAKEMANTISDOMAIN.com/api/rest/plugins/Academic/expiredIssues",
            "method": "GET",
            "timeout": 0,
            "headers": {
                "Authorization": "THE_MANTIS_GENERATED_TOKEN_AS_IS"
            },
            "processData": false,
            "contentType": false,
            "data": form
        };

        $.ajax(settings).done(function (response) {
            console.log(response);
        });
    </script>
</body>
</html>
Where can I learn how to invoke the service from a resource outside the domain context of my mantis application with the token infrastructure? I think I am not far, but it does not work not even deploying the html file in the mantis application domain.

Thanks.
federico
Posts: 35
Joined: 27 Mar 2019, 17:35

Re: Extend rest api

Post by federico »

The error I get is in the following piece of code:

Code: Select all

    protected function finalize(ResponseInterface $response)
    {
        // stop PHP sending a Content-Type automatically
        ini_set('default_mimetype', '');

        if ($this->isEmptyResponse($response)) {
            return $response->withoutHeader('Content-Type')->withoutHeader('Content-Length');
        }

        // Add Content-Length header if `addContentLengthHeader` setting is set
        if (isset($this->container->get('settings')['addContentLengthHeader']) &&
            $this->container->get('settings')['addContentLengthHeader'] == true) {
			
            if (ob_get_length() > 0) {
                throw new \RuntimeException("Unexpected data in output buffer. " .
                    "Maybe you have characters before an opening <?php tag?");
            }
            $size = $response->getBody()->getSize();
            if ($size !== null && !$response->hasHeader('Content-Length')) {
                $response = $response->withHeader('Content-Length', (string) $size);
            }
        }

        return $response;
    }
¿What could cause a dirty output buffer?

Thanks
dregad
Developer
Posts: 75
Joined: 26 Jul 2010, 14:24

Re: Extend rest api

Post by dregad »

Post Reply