Jump to content

Invision Community Blog


Managing successful online communities


4.4: Extend Invision Community with the REST API

Ever since its first release, the REST API built into the Invision Community software has proven to be a very powerful and well-received feature.

We love seeing what our clients and modification authors are able to do with the level of integration afforded to them through this capability, and so it is only natural that we have looked to expand the functionality in our upcoming 4.4 release.

Poll Support

Beginning with 4.4, you will now be able to create and update polls for both topics and blog entries through the REST API. Of course, modification authors can use this new endpoint.

Warn Reasons

You will also now be able to manage warn reasons through the REST API. This includes fetching a list of reasons, as well as fetching an individual reason, creating warn reasons, updating existing warn reasons, and deleting warn reasons.

Event Venues

Event venues can now be listed and individual venues fetched through the REST API, and you can now add, update and delete event venues through the REST API.

Member Notifications

You can now retrieve a list of notifications for a specific member through the REST API, useful if you were to attempt to recreate the notifications menu on a third party website (for example).

Warning Users

The REST API will now expose the warnings a user has received through a new endpoint. Additionally, you can fetch individual warnings, issue new warnings, undo and/or delete issued warnings, and acknowledge warnings through the REST API. If you are building a site wrapper around your community, you can leverage this functionality to ensure that users are unable to post elsewhere on your site if they have unacknowledged warnings within the community (and also to provide them with a way to acknowledge those warnings right on your site).

2027917625_RESTOAuth2018-11-3013-02-09.thumb.jpg.f19d600c0d4483cfbb6d0849d0e661f9.jpg

The REST API Reference

Node permissions

Beginning with 4.4, you will now be able to set the permissions for a node when adding or updating it through the REST API (for example, you can now adjust the permissions for a forum or a downloads category through the REST API). Many clients noticed that while they could create new nodes through the API, the nodes would be unusable until an administrator manually went in and specified the permissions, so this change can eliminate this extra step in many situations.

Event filtering

You will now also be able to filter the events you pull through the Calendar REST API endpoints by start and end date (e.g. so you can show events within a specific time frame, such as the current week), and you can now also specify to sort the events returned by the event start date or the event end date.

Clubs

And finally, for those who leverage clubs on their communities, we have built in full REST API support for clubs. You can list all clubs, return a specific club, create new clubs, update existing clubs, and delete clubs through the REST API. Further, you can list all members in a club, add a specific member to a specific club, remove a member from a club, fetch the content types available for use within a club (i.e. so you can determine which applications are installed and have club support on a given site), fetch the nodes (displayed as tabs/sections within a club) created within a club, and delete nodes from a club. Important behind the scenes steps, such as generating invoices for members requesting to join paid clubs, are all handled automatically for you when using the REST API.

We believe these changes will help clients better integrate with our software and open up new possibilities with their websites.

Would you like us to add any other endpoints? Let us know in the comments below!


Comments

Recommended Comments

Since the API provides means to retrieve content and user data, should it also provide a way to mark content as read? 

Or is this already covered? (I have to admit I haven't researched this before asking)

Share this comment


Link to comment
Share on other sites
7 minutes ago, TSP said:

Since the API provides means to retrieve content and user data, should it also provide a way to mark content as read? 

 Or is this already covered? (I have to admit I haven't researched this before asking)

No read markings.  Also read data should be sent via api.  It'd be nice, but there's too much detail.   

Share this comment


Link to comment
Share on other sites
  • Return content a guest would see if no token has been sent with the request.
  • Requesting the forum list (/api/forums/forums/ does not make any sense at the moment b/c you can not differentiate if you have a category or if an item is a parent of another one. Please organize the returned structure in a better way or give the possibility to organize the returned structure via parameters.
  • Return unread content for authenticated members
  • Return the topic a post is related to
  • Upload images and other media
  • Mark topic / posts as read
  • Flag whether a topic / post is marked as read or not
Edited by tsdevelopment

Share this comment


Link to comment
Share on other sites

I have read about it but honestly I have no idea how it can benefit me. In what circumstances I could for example take advantage of the REST API? I'm running a community for 13 years now and when it come to API stuff I'm clueless.

Share this comment


Link to comment
Share on other sites
2 minutes ago, Maxxius said:

I have read about it but honestly I have no idea how it can benefit me. In what circumstances I could for example take advantage of the REST API? I'm running a community for 13 years now and when it come to API stuff I'm clueless.

For example if you publish your own APP and need to fetch your community data.

Share this comment


Link to comment
Share on other sites
3 hours ago, Maxxius said:

I have read about it but honestly I have no idea how it can benefit me. In what circumstances I could for example take advantage of the REST API? I'm running a community for 13 years now and when it come to API stuff I'm clueless.

Many of our enterprise clients leverage the REST API to add community-specific data to their front end websites. Things like "recent topics" or (in more advanced cases), user-specific data such as the number of private messages a user has on the community (e.g. recreating the header bar).

It really sort of depends on your needs.

2 minutes ago, Tom S. said:

How about more integration with with Commerce?

Creating invoices, managing purchases, etc ...

When you say "managing purchases", what are you after specifically?

Share this comment


Link to comment
Share on other sites
1 hour ago, bfarber said:

When you say "managing purchases", what are you after specifically?

From the point of view of managing subscriptions. So, the ability to disable renewals, upgrade/downgrade.

It would be awesome to be able to sell a product/subscription and manage them using the API.

Share this comment


Link to comment
Share on other sites

@bfarber Historically one of the IPS "enterprise" offerings has been a comments widget that can be placed on any page, ala Disqus - at least that's my understanding of how it works?

What I'd really like to see is that particular functionality democratized & offered as a frontend component that works hand-in-hand with your REST API. Our site has thousands of pages that are stored in a separate database, outside of IPS - for good reasons. I'd LOVE to offer integrated comment threads on these pages, to tie the entire community together. So whatever combination of REST API endpoints *AND* frontend JavaScript would be necessary to make that happen, that's my number one (by far) request.

In the absence of something like this, my community and others with a similar use case are forced to resort to Facebook comments widget or Disqus, which takes us further away from IPS... I haven't taken that step yet because I've been waiting & waiting & waiting to see if something could be done via IPS.

Thoughts?

Edited by djpretzel

Share this comment


Link to comment
Share on other sites

+1 on managing invoices. It'd be nice to create an invoice from the API, have a paypal url returned or a post request to pass credit card details under SSL to complete purchases off site.

Share this comment


Link to comment
Share on other sites

Another point about the Commerce API. It has a lot of Getter end points only.

792587F6-E106-4A02-8625-B89A580F944C.thumb.jpeg.e59c961410ab64d3d73e5b3b214ac502.jpeg

Having the power to post and delete in all these endpoints would be fantastic.

Im trying to think from the point of view of creating a custom mobile app that communicates with the master web suite. Currently, I would have to create my own custom API’s to make it possible.

Share this comment


Link to comment
Share on other sites
33 minutes ago, jesuralem said:

Ability to post notifciations would be great, so the IPS notification system could be used by the whole site and not limited to IPS.

If you're interested into this via a 3rd party app, you could use https://invisioncommunity.com/files/file/8388-custom-notifications/ :) 

Share this comment


Link to comment
Share on other sites

Please tell me if I'm wrong, but the API allows a new post to get created doesn't it? I have weather software that monitors the EMWIN network, and currently the software can post directly to FB, Twitter, send email, upload to website, etc. I would like to talk to the developer to add an option to make a direct post to my Invision. Doable?

Share this comment


Link to comment
Share on other sites
30 minutes ago, brueckscca said:

Please tell me if I'm wrong, but the API allows a new post to get created doesn't it? I have weather software that monitors the EMWIN network, and currently the software can post directly to FB, Twitter, send email, upload to website, etc. I would like to talk to the developer to add an option to make a direct post to my Invision. Doable?

Yes, the REST API can be used for this.

Share this comment


Link to comment
Share on other sites
On 11/30/2018 at 2:57 PM, tsdevelopment said:
  • Return content a guest would see if no token has been sent with the request.
  • Requesting the forum list (/api/forums/forums/ does not make any sense at the moment b/c you can not differentiate if you have a category or if an item is a parent of another one. Please organize the returned structure in a better way or give the possibility to organize the returned structure via parameters.
  • Return unread content for authenticated members
  • Return the topic a post is related to
  • Upload images and other media
  • Mark topic / posts as read
  • Flag whether a topic / post is marked as read or not

NEED! +1

Share this comment


Link to comment
Share on other sites

The endpoints that I could really use for our community:

  • Endpoint for getting image thumbnails, not just the images themselves.
  • Endpoint for getting gallery image list from one specifiec category.

Share this comment


Link to comment
Share on other sites
49 minutes ago, GabijaCiju said:

Endpoint for getting gallery image list from one specifiec category.

You can use the /gallery/images endpoint for this, it accepts the category as parameter

 * @apiparam	string	categories		Comma-delimited list of category IDs (will also include images in albums in those categories)

 

And the gallery-image apiresponse contains already what you suggested.

	 * @apiresponse	object					images			URLs to where the images are stored. Keys are 'original', 'large', and 'small', and values are URLs to the corresponding images

 

Share this comment


Link to comment
Share on other sites

I remember that it was not possible to respect user permissions, is that still true? If I make a rest api request to a certain topic, is there a check if a user/guest is allowed to read this topic?

Share this comment


Link to comment
Share on other sites
10 hours ago, jair101 said:

I remember that it was not possible to respect user permissions, is that still true? If I make a rest api request to a certain topic, is there a check if a user/guest is allowed to read this topic?

This was already implemented for 4.3 🙂

 

Quote

Permission awareness

Several REST API endpoints are now permission-aware when combined with Oauth functionality built into Invision Community 4.3. This means that many REST API endpoints can be called using a specific user's access token, and only results that the specific user would normally be able to see will be returned (and/or they will only be able to submit to areas they normally have permission to). 

 

Share this comment


Link to comment
Share on other sites

I'll be jumping into learning this stuff full time in January.  Wow, it's hard to get a handle on all the different things you need to learn and where to start. 

I am curious why, say with running Drupal as headless/decoupled they suggest running it along side NodeJs.   Is that strictly for additional application functionality the CMS itself doesn't provide or is that necessary to make it work? 

wrt to running a PWA or headless IPS can it be done with vanilla Javascript or  js + react?  

My plan was html/css -> JS -> React  and focus on the front end using IPS as the back end.  However, it seems node keeps getting thrown into the mix. 

An example of the kind of thing I want to add to my site:  A line up builder so people can create and post lineups in the forum or in articles. 

 

Share this comment


Link to comment
Share on other sites

I'll be posting this in feedback as well, as @bfarber recommends, but I think the following should strongly be considered:

  • Make the REST API mandatory (at least for access from same host)
  • Start using the REST API within the default IPS theme for things like the widgets, user status
  • In other words, even for the core product, start moving to more of an SPA paradigm, with graceful fallback to server-side content when possible

In this fashion, the REST API becomes more immediately useful to all developers, because it's guaranteed to be present and is hooked in to the way the core product functions, OOTB.

Share this comment


Link to comment
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  Ask A Question ×