You are viewing limited content. For full access, please sign in.

Question

Question

Discussion: Will Laserfiche ever get a unified, "RESTful" HTTP API?

asked on January 23 Show version history

Many enterprise systems today, especially those that are cloud-based, have resource-oriented APIs that can be accessed over HTTP, which allow developers and system integrators to connect them to line of business software with relative ease. As the Laserfiche ecosystem grows, it is becoming more and more clear that one of the things holding it back is the lack of such an API. And frankly, it is confusing and somewhat concerning that there is nothing on the roadmap to develop one, at least as far as I'm aware.

Let me give a simple "real-life" example from just this week. We're working with a customer who uses a third-party cloud-based system to generate sales quotes as clean, professional-looking PDFs. The customer asked us if it is possible to store these PDFs automatically in a specific folder in Laserfiche, along with some metadata (template name, salesperson name and branch, and so on). The third-party system in question has webhooks that allow the generated PDFs to be sent elsewhere using HTTP POST, which allows the system administrator to easily configure a destination that can accept such requests and process them. The idea is that once a quote gets signed and accepted by the client, its PDF can then be sent to another system for archival.

The problem is that Laserfiche doesn't have anything that can ingest such requests. Getting it to do so would require writing a web service that utilizes the Laserfiche SDK behind the scenes, and writing and maintaining such services requires proficiency in .NET/C#, as well as familiarity with the service-oriented architecture of the LF ecosystem. Furthermore, there is no convenient method to authenticate the requests, so one either needs to be developed from scratch (LFDS doesn't have an open, standards-based protocol that can be consumed by non-LF applications, as far as I'm aware), or the web service needs to use the hard-coded credentials of a named user that has access to the destination repository.

The ideal solution would be a Laserfiche product/module (let's call it "LFAPI" for the sake of simplicity) that can be installed on a web server and configured to route requests coming to various endpoints over to their corresponding LF services. For example:

Fetch a document/folder: 
GET https://mydomain.com/lfapi/repositories/<repo_name>/<entry_id>

Store a document: 
POST https://mydomain.com/lfapi/repositories/<repo_name>/ (include document info in the request body, such as the image, metadata, options, etc.)

Update document metadata: 
PUT https://mydomain.com/lfapi/repositories/<repo_name>/<entry_id> (include desired updates in request body, e.g. metadata fields and values)

Invoke a workflow: 
POST https://mydomain.com/lfapi/workflows/<workflow_id> (include input params in the request body)

Get the status of a workflow instance: 
GET https://mydomain.com/lfapi/workflows/<instance_id> 

For authentication, you should be able to tie API Keys to user accounts, then include one as a bearer token in the request header for the LFAPI service to check and authenticate/authorize. Again, these types of authentication systems are super common; you get the idea.

To conclude, we always talk about how Laserfiche is easy to integrate with other systems, but I think everyone knows that that's just a half-truth — one that is becoming less true as time goes by. Sure, Workflow can send web requests, and read from and write to database tables and so on. But truly robust systems require two-way integrations, which means LF needs to be able to easily receive documents and data from outside as well. And currently the mechanisms for that need to be custom-developed, which makes them expensive and usually very clunky too because you always end up fighting the existing architecture and working around its design (not to mention licensing!) limitations. But if an "LFAPI" product existed — one that essentially acted as a unified gateway between Laserfiche and the outside world — it would immediately make Laserfiche a much, much more viable middleware piece in complex systems.

8 0

Replies

replied on January 23

Yes wink

 

8 0
replied on January 23

Color me intrigued! We used the SDK to build an API for basic functions like document and metadata retrieval, but our next "target" was going to be Workflow initiation.

0 0
replied on January 30

Just to be clear, you know Workflow already has an HTTP REST API for invoking workflows and querying their statuses, right?

0 0
replied on January 30

Yes, but to be totally honest the API help documentation hosted by WF doesn't provide much guidance on how to actually use it via pure HTTP requests. The whitepaper and most of the examples on Answers use C# activities to consume the web service rather than using JSON posts, so we were just going to go the code route and integrate the functionality into the API we built for document and metadata retrieval.

1 0
replied on January 30

Agreed completely Jason.

To be honest, Laserfiche should look at and get inspiration from the Stripe API, which has phenomenal documentation that makes it a joy to use. Notable points:

1. Documentation is publicly accessible, not hidden behind a login screen (or a module install, like with the LF SDK)

2. The page design is slick, coherent and modern.

3. Every object, function call (create, update, etc.) and parameter is explained in detail, with examples.

4. Examples available in multiple languages (since an HTTP interface enables client libraries to be written in any language)

If LF manages to create something like this, it would really move to the next level.

1 0
replied on January 30

Totally agree Ege - the Stripe API documentation is fantastic.

With that said, the Workflow Web Services REST API is fairly easy to use. I'd hate for you to unnecessarily reinvent that particular wheel.

I've attached a simple demo with two workflows bundled in a .wfi file. The first makes a web service call to invoke the other and pass an input parameter. You and Jason should have no trouble understanding it. Had to tack a .txt on the .wfi to get around file extension upload restrictions, so remove that after downloading. Import to any Workflow server and run the "[Web Service] Invoking WF" manually to see the demo in action.

You can view the actual Workflow REST API reference by going to the following address on a Workflow server with Workflow Web Services configured:
http://localhost/Workflow/api/help

Though it isn't as pretty as Stripe, the information is there. Example screenshots below.

Documentation root:

Invoking instances:

Hope that's helpful for now!

1 0
replied on January 30

Thanks Sam,

I have looked through the hosted reference page before, I guess I just never put a lot of time into testing it out and misunderstood some of the information. I think the biggest obstacle I had was trying to determine what minimum parameters are required and I believe there are a few where I wasn't sure of their purpose.

To be honest, it wasn't until recently that I even realized that you could create straight HTTP/JSON requests as I originally thought it could only be done through the web service client; this was obviously just a misunderstanding due to the Answers posts I had found at the time and the reference page indicating a client was needed to use services.

http://localhost/workflow/api/RestWorkflowAPI.svc

1 0
replied on January 30

Same, Jason. I have no idea how to make sense of that information, because as you say, what is required and what is optional is not clear. The first time I used the API I remember it took a ton of trial and error and it was very unpleasant, to say the least.

1 0
replied on January 23

Well said Ege. We get asked in almost every sales cycle if we have an API (REST or otherwise). We have built some projects using the WorkFlow WebService to receive documents and Metadata into LF but there are always challenges with supporting this as each is a one off. A true API would be so much better. Would be nice if we could have such an announcement at EMPower 2020.

2 0
replied on January 23

Would be nice if we could have such an announcement at Empower 2020.

 

 That does sound like a neat idea. 

3 0
You are not allowed to follow up in this post.

Sign in to reply to this post.