Documentation for Job REST API is missing details

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation for Job REST API is missing details

vmassol
Administrator
Hi guys,

I’m trying to use the Job REST API but the doc is pretty poor at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HJobresources

For example to execute a job it says that you only need to pass a “jobType” described as "The type of the job to pass to the Job Executor” … errr what’s the type and what are the valid values? Would be nice to have some example too.

Also it doesn’t mention any payload that I have to send but I guess I need to describe the job that I need to execute. What’s the format?

It also says:


Since 9.2RC1 jobs started trough the REST API automatically get their runtime context injected with the following REST HTTP request context properties:

        • current wiki
        • current user
        • request URL and parameters


What if I want to specify the wiki, user for ex? How do I do that?

At the end there are examples of file format at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HFormatsoffiles but nothing for jobs.

Could someone help improve the doc so that I can try to use it?

Thanks!
-Vincent





Reply | Threaded
Open this post in threaded view
|

Re: Documentation for Job REST API is missing details

Thomas Mortagne
Administrator
On Sun, Jan 14, 2018 at 11:57 AM, Vincent Massol <[hidden email]> wrote:
> Hi guys,
>
> I’m trying to use the Job REST API but the doc is pretty poor at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HJobresources
>
> For example to execute a job it says that you only need to pass a “jobType” described as "The type of the job to pass to the Job Executor” … errr what’s the type and what are the valid values? Would be nice to have some example too.

The type is the same job type you have in the Job module document
ation at http://extensions.xwiki.org/xwiki/bin/view/Extension/Job+Module#HUseanexistingjob.
i.e. the hint of the Job component you want to execute, it's not
possible to give a list of those types.

>
> Also it doesn’t mention any payload that I have to send but I guess I need to describe the job that I need to execute. What’s the format?

This API document is quite JAX-RS oriented so you can see the class
you would send in Java in the "Accepted Media types:" section, here
it's JobRequest (complete name being
org.xwiki.rest.model.jaxb.JobRequest).

>
> It also says:
>
> “
> Since 9.2RC1 jobs started trough the REST API automatically get their runtime context injected with the following REST HTTP request context properties:
>
>         • current wiki
>         • current user
>         • request URL and parameters
> “
>
> What if I want to specify the wiki, user for ex? How do I do that?

Keep in mind you are not reading an Extension module documentation but
a Job module one.

The namespace(s) where you want to install extensions is indicated in
the job request in case of install job.

>
> At the end there are examples of file format at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HFormatsoffiles but nothing for jobs.

Yes will need to add a few examples. In the meantime you can see how
the JAX-RS XML of an install request looks by asking for the
/jobstatus/ of some previous installed extension.

>
> Could someone help improve the doc so that I can try to use it?
>
> Thanks!
> -Vincent
>
>
>
>
>



--
Thomas Mortagne
Reply | Threaded
Open this post in threaded view
|

Re: Documentation for Job REST API is missing details

vmassol
Administrator
Thanks Thomas, see below

> On 14 Jan 2018, at 17:32, Thomas Mortagne <[hidden email]> wrote:
>
> On Sun, Jan 14, 2018 at 11:57 AM, Vincent Massol <[hidden email]> wrote:
>> Hi guys,
>>
>> I’m trying to use the Job REST API but the doc is pretty poor at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HJobresources
>>
>> For example to execute a job it says that you only need to pass a “jobType” described as "The type of the job to pass to the Job Executor” … errr what’s the type and what are the valid values? Would be nice to have some example too.
>
> The type is the same job type you have in the Job module document
> ation at http://extensions.xwiki.org/xwiki/bin/view/Extension/Job+Module#HUseanexistingjob.
> i.e. the hint of the Job component you want to execute, it's not
> possible to give a list of those types.

It’s possible to give examples. That would already help a lot.

>
>> Also it doesn’t mention any payload that I have to send but I guess I need to describe the job that I need to execute. What’s the format?
>
> This API document is quite JAX-RS oriented so you can see the class
> you would send in Java in the "Accepted Media types:" section, here
> it's JobRequest (complete name being
> org.xwiki.rest.model.jaxb.JobRequest).

Sure but this is not very explicit for users reading the documentation. You shouldn’t have to read the source code to be able to use the REST API IMO.

>
>>
>> It also says:
>>
>> “
>> Since 9.2RC1 jobs started trough the REST API automatically get their runtime context injected with the following REST HTTP request context properties:
>>
>>        • current wiki
>>        • current user
>>        • request URL and parameters
>> “
>>
>> What if I want to specify the wiki, user for ex? How do I do that?
>
> Keep in mind you are not reading an Extension module documentation but
> a Job module one.

I didn’t understand this remark.

>
> The namespace(s) where you want to install extensions is indicated in
> the job request in case of install job.

Ok

>
>>
>> At the end there are examples of file format at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HFormatsoffiles but nothing for jobs.
>
> Yes will need to add a few examples. In the meantime you can see how
> the JAX-RS XML of an install request looks by asking for the
> /jobstatus/ of some previous installed extension.

Thanks, FTR I got the following for the FAQ extension:

URL:

http://localhost:8080/xwiki/rest/jobstatus/extension/action/org.xwiki.contrib%3Aapplication-faq-ui/wiki%3Axwiki/?request=true

Result:

https://gist.github.com/vmassol/e553ce36b24fbb59d1110e256ab5954f

Now I need to figure what’s the minimal list of properties that I have to pass… There seems to be a lot:
* extensions
* extensions.excluded
* rewriter
* extension.properties
* rootModificationsAllowed
* caller.reference
* interactive
* checkrights
* context.action
* user.reference
* context.wiki
* namespaces

There seems to be some duplication.

For example the user used to install the extension is defined in:
* extension.properties (as a String)
* user.reference (as a serialized reference)

Whether the job is interactive or not:
* <interactive>true</interactive>
* And also in the “interactive” property

Any idea about what’s the minimum I need to pass?

Thanks
-Vincent


>
>>
>> Could someone help improve the doc so that I can try to use it?
>>
>> Thanks!
>> -Vincent
>>
>>
>>
>>
>>
>
>
>
> --
> Thomas Mortagne

Reply | Threaded
Open this post in threaded view
|

Re: Documentation for Job REST API is missing details

vmassol
Administrator
BTW since I am in Java, is there an example somewhere of making a PUT REST call from Java, especially for installing an extension? In other words are we using the Job REST API somewhere?

It would be nice that we add a PUT example at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HInteractingwiththeXWikiRESTfulAPI

Once I succeed, I can document an example from Java.

Thanks
-Vincent

> On 14 Jan 2018, at 18:50, Vincent Massol <[hidden email]> wrote:
>
> Thanks Thomas, see below
>
>> On 14 Jan 2018, at 17:32, Thomas Mortagne <[hidden email]> wrote:
>>
>> On Sun, Jan 14, 2018 at 11:57 AM, Vincent Massol <[hidden email]> wrote:
>>> Hi guys,
>>>
>>> I’m trying to use the Job REST API but the doc is pretty poor at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HJobresources
>>>
>>> For example to execute a job it says that you only need to pass a “jobType” described as "The type of the job to pass to the Job Executor” … errr what’s the type and what are the valid values? Would be nice to have some example too.
>>
>> The type is the same job type you have in the Job module document
>> ation at http://extensions.xwiki.org/xwiki/bin/view/Extension/Job+Module#HUseanexistingjob.
>> i.e. the hint of the Job component you want to execute, it's not
>> possible to give a list of those types.
>
> It’s possible to give examples. That would already help a lot.
>
>>
>>> Also it doesn’t mention any payload that I have to send but I guess I need to describe the job that I need to execute. What’s the format?
>>
>> This API document is quite JAX-RS oriented so you can see the class
>> you would send in Java in the "Accepted Media types:" section, here
>> it's JobRequest (complete name being
>> org.xwiki.rest.model.jaxb.JobRequest).
>
> Sure but this is not very explicit for users reading the documentation. You shouldn’t have to read the source code to be able to use the REST API IMO.
>
>>
>>>
>>> It also says:
>>>
>>> “
>>> Since 9.2RC1 jobs started trough the REST API automatically get their runtime context injected with the following REST HTTP request context properties:
>>>
>>>       • current wiki
>>>       • current user
>>>       • request URL and parameters
>>> “
>>>
>>> What if I want to specify the wiki, user for ex? How do I do that?
>>
>> Keep in mind you are not reading an Extension module documentation but
>> a Job module one.
>
> I didn’t understand this remark.
>
>>
>> The namespace(s) where you want to install extensions is indicated in
>> the job request in case of install job.
>
> Ok
>
>>
>>>
>>> At the end there are examples of file format at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HFormatsoffiles but nothing for jobs.
>>
>> Yes will need to add a few examples. In the meantime you can see how
>> the JAX-RS XML of an install request looks by asking for the
>> /jobstatus/ of some previous installed extension.
>
> Thanks, FTR I got the following for the FAQ extension:
>
> URL:
>
> http://localhost:8080/xwiki/rest/jobstatus/extension/action/org.xwiki.contrib%3Aapplication-faq-ui/wiki%3Axwiki/?request=true
>
> Result:
>
> https://gist.github.com/vmassol/e553ce36b24fbb59d1110e256ab5954f
>
> Now I need to figure what’s the minimal list of properties that I have to pass… There seems to be a lot:
> * extensions
> * extensions.excluded
> * rewriter
> * extension.properties
> * rootModificationsAllowed
> * caller.reference
> * interactive
> * checkrights
> * context.action
> * user.reference
> * context.wiki
> * namespaces
>
> There seems to be some duplication.
>
> For example the user used to install the extension is defined in:
> * extension.properties (as a String)
> * user.reference (as a serialized reference)
>
> Whether the job is interactive or not:
> * <interactive>true</interactive>
> * And also in the “interactive” property
>
> Any idea about what’s the minimum I need to pass?
>
> Thanks
> -Vincent
>
>
>>
>>>
>>> Could someone help improve the doc so that I can try to use it?
>>>
>>> Thanks!
>>> -Vincent
>>>
>>>
>>>
>>>
>>>
>>
>>
>>
>> --
>> Thomas Mortagne

Reply | Threaded
Open this post in threaded view
|

Re: Documentation for Job REST API is missing details

Thomas Mortagne
Administrator
In reply to this post by vmassol
On Sun, Jan 14, 2018 at 6:50 PM, Vincent Massol <[hidden email]> wrote:

> Thanks Thomas, see below
>
>> On 14 Jan 2018, at 17:32, Thomas Mortagne <[hidden email]> wrote:
>>
>> On Sun, Jan 14, 2018 at 11:57 AM, Vincent Massol <[hidden email]> wrote:
>>> Hi guys,
>>>
>>> I’m trying to use the Job REST API but the doc is pretty poor at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HJobresources
>>>
>>> For example to execute a job it says that you only need to pass a “jobType” described as "The type of the job to pass to the Job Executor” … errr what’s the type and what are the valid values? Would be nice to have some example too.
>>
>> The type is the same job type you have in the Job module document
>> ation at http://extensions.xwiki.org/xwiki/bin/view/Extension/Job+Module#HUseanexistingjob.
>> i.e. the hint of the Job component you want to execute, it's not
>> possible to give a list of those types.
>
> It’s possible to give examples. That would already help a lot.

The goal of this API is to provide an HTTP version of
http://extensions.xwiki.org/xwiki/bin/view/Extension/Job+Module#HUseanexistingjob
but it's working exactly the same way. I will add some notes about the
general idea being this API and give example of modules providing jobs
in Job Module documentation.

The missing documentation is probably more in the Extension module
which need something about the REST way of using extension related
jobs (and same for other modules which provide public jobs).

For install job the type is "install".

>
>>
>>> Also it doesn’t mention any payload that I have to send but I guess I need to describe the job that I need to execute. What’s the format?
>>
>> This API document is quite JAX-RS oriented so you can see the class
>> you would send in Java in the "Accepted Media types:" section, here
>> it's JobRequest (complete name being
>> org.xwiki.rest.model.jaxb.JobRequest).
>
> Sure but this is not very explicit for users reading the documentation. You shouldn’t have to read the source code to be able to use the REST API IMO.

I never said it's good documentation to read the code. This whole page
is JAX-RS/JAXB oriented in practice and give class names for
body/response and, in some cases, one XML content example that might
not be complete or up to date. Since I did not had much time I just
followed the same format for the generic API planning a more complete
example on Extension Manager documentation side for extension use
case.

>
>>
>>>
>>> It also says:
>>>
>>> “
>>> Since 9.2RC1 jobs started trough the REST API automatically get their runtime context injected with the following REST HTTP request context properties:
>>>
>>>        • current wiki
>>>        • current user
>>>        • request URL and parameters
>>> “
>>>
>>> What if I want to specify the wiki, user for ex? How do I do that?
>>
>> Keep in mind you are not reading an Extension module documentation but
>> a Job module one.
>
> I didn’t understand this remark.

You don't really care about Job default runtime context in your case
since most Extension Manager jobs and API don't not care about
context.

>
>>
>> The namespace(s) where you want to install extensions is indicated in
>> the job request in case of install job.
>
> Ok
>
>>
>>>
>>> At the end there are examples of file format at http://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/XWikiRESTfulAPI#HFormatsoffiles but nothing for jobs.
>>
>> Yes will need to add a few examples. In the meantime you can see how
>> the JAX-RS XML of an install request looks by asking for the
>> /jobstatus/ of some previous installed extension.
>
> Thanks, FTR I got the following for the FAQ extension:
>
> URL:
>
> http://localhost:8080/xwiki/rest/jobstatus/extension/action/org.xwiki.contrib%3Aapplication-faq-ui/wiki%3Axwiki/?request=true
>
> Result:
>
> https://gist.github.com/vmassol/e553ce36b24fbb59d1110e256ab5954f
>
> Now I need to figure what’s the minimal list of properties that I have to pass… There seems to be a lot:
> * extensions
> * extensions.excluded
> * rewriter
> * extension.properties
> * rootModificationsAllowed
> * caller.reference
> * interactive
> * checkrights
> * context.action
> * user.reference
> * context.wiki
> * namespaces

The EM script service put many things in the request but it does not
mean you need all of them :) It's just a good example of how the
XML/JSON looks.

>
> There seems to be some duplication.
>
> For example the user used to install the extension is defined in:
> * extension.properties (as a String)
> * user.reference (as a serialized reference)

It's actually two different information which are not used at the same
level in practice. They are usually the same in standard EM UI but
they might be different in some cases: one is mostly the user to check
rights against and the other is the user to remember as the one who
asked for the install. I doubt you care about any of those in your use
case.

>
> Whether the job is interactive or not:
> * <interactive>true</interactive>
> * And also in the “interactive” property
>
> Any idea about what’s the minimum I need to pass?

There is no real minimum other than indicating the extension you want
to install, it then depends which behavior you want (the id if you
want to serialize the status or have the progress/log appear in the EM
UI, remember who made the install, install on specific namespace,
etc.).

This XML is just a JAX-RS serialized version of the InstallRequest so
the most accurate documentation will probably be InstallRequest
javadoc and a complete example would be
ExtensionManagerScriptService#install source code I think (but it's
doing much more than what you need like rights checking and rewriter
so just pick what you need which is probably not much more than the id
and even that might not be really needed from what I know about your
use case).

>
> Thanks
> -Vincent
>
>
>>
>>>
>>> Could someone help improve the doc so that I can try to use it?
>>>
>>> Thanks!
>>> -Vincent
>>>
>>>
>>>
>>>
>>>
>>
>>
>>
>> --
>> Thomas Mortagne
>



--
Thomas Mortagne