The modern approach to API development is often associated with the use of the cloud. Therefore, it has become increasingly important to present novel ideas capable of improving users' and developers' digital experiences. With that in mind, the DynamicDocs API approach to PDF generation is to use LaTeX, a language that is designed for high-quality typesetting.
The DynamicDocs API provides an alternative to deploying a stand-alone PDF-generating solution which is a viable option for startups and enterprises. The API approach allows developers to test the solution quickly via Postman and generate large amounts of PDF while incorporating graphics and logic into the templates. In the previous article, we introduced a new feature of the API, JSON to PDF Templates, which enable users to generate PDFs using ready-made templates. In this article, we present a specific type of JSON to PDF template called TEX to PDF, which allows users to send their own LaTeX source file and compile it via the API.
What is LaTeX?
LaTeX is a computer language used for document preparation, specifically PDF generation. LaTeX source files have a Tex extension, which are typically compiled into PDFs. Although it is very popular in academia and used for dissertations and journal articles, the language lends itself well to creating great-looking documents in general. One of its advantages is the separation of document content and the rules governing the look and feel of the document. A notable disadvantage of LaTeX is that the learning curve for writing the rules of the document layout can be steep and require a significant investment in time for the user. To circumvent this, DynamicDocs API has a library of ready-made PDF to JSON templates which do not require any knowledge of LaTeX. However, this article assumes that you already have a working Tex file which needs to be compiled.
LaTeX Compilers
To convert LaTeX source files into PDFs, one needs a compiler. DynamicDocs API offers two compilers, namely pdfLaTeX and LuaLaTeX. Tex to PDF Template range consists of two general templates allowing users to upload their own tex file and optionally include Base64 encoded images in the JSON payload. The templates correspond to the two compilers available. For more information on calling the two templates, visit Tex to PDF with pdfLaTeX Template and Tex to PDF with LuaLaTeX Template.
Let's now look at the case when it makes sense to use TEX to PDF conversion with an API.
Considerations for TEX to PDF with DynamicDocs API
The following list explains the criteria for when using DynamicDocs API makes sense for TEX to PDF conversion:
You need to generate several PDF documents and want to do it programmatically.
You have (or can create) a Tex file which can be adjusted with the dynamic data.
You can make a POST request to the API with your TeX file formatted as JSON.
If any of those points do not apply to your use case, you will likely be better off using an online Tex to PDF converter or Overleaf.
Tutorial to Convert TEX to PDF with DynamicDocs API
Consider a situation where you have to create PDF name tags where the underlying data is stored in the system and can be accessed programmatically. The aim is to create a PDF document which looks as follows:
Example of a name tag we would like to reproduce with LaTeX
To get started with DynamicDocs API, you will need to sign up for an account with ADVICEment.io. Without needing to give bank card information, the new accounts are automatically set up with a FREE plan which offers a limited number of API calls. Once the account email address is confirmed, users can log in and access the Dashboard, where they can get their account API key:
In the DynamicDocs API Dashboard, under Account Details, you will be able to see if you have generated your API Key.By clicking Edit under Account Details and clicking Generate Account Security Token, the API Key will be shown.
We are now almost ready to make the API call. To create the PDF document above, we have written the following Tex file:
Changing this Tex file by including different names and titles for each name tag can be done programmatically. Although at first glance, this looks like a normal Tex file, notice the \advGetImage function, which is a custom function used within DynamicDocs API to convert the image from JSON payload and insert it into the file. Notice that it references image1 key in the JSON payload below. For more information on this function, visit our API documentation page.
Now we are ready to formulate our JSON payload, which looks as follows:
Note that the stringified Tex file has to be put under the texFileContent key in the JSON. Furthermore, the texFileContent value contains double backslashes where single backslashes were previously used in the Tex file. The double backslashes are a result of stringifying the TEX file. Finally, the JSON contains a Base64 encoded image which is referenced in the \advGetImage function above. This allows users to make images dynamic in the documents.
We are now ready to make the API call and POST the JSON above to TEX to PDF with pdfLaTeX template endpoint:
To do so successfully, you will have to authenticate your API request by including the API key as a header parameter as follows:
Header Key
Value
Adv-Security-Token
{{Your Account API Key}}
To make the API call above we suggest viewing the DynamicDocs API – Public Workspace via Postman. Alternatively you can import the TEX to PDF Template API Calls via the button below.
The response of the API call is a simple JSON with the location of the Status JSON. To see whether the PDF was generated successfully, we can GET the Status JSON using the URL found in the response. If the PDF is generated successfully, the Status JSON will look as follows and contain the link to download the PDF:
We have completed the LaTeX to PDF process using an API. Of course, the Tex file above can be replaced with any working LaTeX source file. The approach above gives developers a powerful option of creating a large variety of different document types.
Final Remarks
As outlined in this article, DynamicDocs API caters for a specific use case when doing TEX to PDF conversion (see the Consideration section to see whether your use case fits). In an event where you have ticked all the conditions, TEX to PDF templates give the option of creating different document types, provided users can create your their own working Tex file and dynamically populate it with their data. DynamicDocs API runs a full TeX Live 2021 Distribution, meaning that users have access to an extensive range of the latest LaTeX packages and fonts. For quick integration, follow the steps above or visit DynamicDocs API – Public Workspace via Postman page.
