Learning Documentation CommunityOpen ExchangeGlobal Masters Certification Partner Directory Ideas Portal

Submit application

iris-python-flask-api-template

Downloads11

Bookmark

This application is not supported by InterSystems Corporation. Please be notified that you use it at your own responsibility.

Details

Releases

Reviews

Issues

Articles

1. intersystems-iris-docker-rest-template

This is a template of a REST API application built in python in InterSystems IRIS. It also has OPEN API spec, can be developed with Docker and VSCode.

1. intersystems-iris-docker-rest-template
2. Prerequisites
3. Installation
4. How it works
5. How to Work With it
6. How to start coding
7. What's inside the repo

2. Prerequisites

Make sure you have git and Docker desktop installed.

It is to be noted that the table Sample.Person was already created in advance for the demo using in the management portal in the sql tab:

CREATE TABLE Sample.Person (
     Company                                  <span class="pl-k">VARCHAR</span>(<span class="pl-c1">50</span>),
     DOB                                      <span class="pl-k">DATE</span>,
     Name                                     <span class="pl-k">VARCHAR</span>(<span class="pl-c1">4096</span>),
     Phone                                    <span class="pl-k">VARCHAR</span>(<span class="pl-c1">4096</span>),
     Title                                    <span class="pl-k">VARCHAR</span>(<span class="pl-c1">50</span>)

)

3. Installation

3.1. Installation for development

Clone/git pull the repo into any local directory e.g. like it is shown below:

$ git clone https://github.com/grongierisc/iris-python-flask-api-template.git

Open the terminal in this directory and run:

$ DOCKER_BUILDKIT=1 docker-compose up -d --build

3.2. Management Portal and VSCode

This repository is ready for VS Code.

Open the locally-cloned formation-template-python folder in VS Code.

If prompted (bottom right corner), install the recommended extensions.

3.3. Having the folder open inside the container

It is really important to be inside the container before coding.
For this, docker must be on before opening VSCode.
Then, inside VSCode, when prompted (in the right bottom corner), reopen the folder inside the container so you will be able to use the python components within it.
The first time you do this it may take several minutes while the container is readied.

More information here

By opening the folder remote you enable VS Code and any terminals you open within it to use the python components within the container. Configure these to use /usr/irissys/bin/irispython

4. How it works

The app.py, once launched (inside the container) will gather CRUD request.
Depending on the type of the request, the right message will be created to send to the FlaskService, this service will call the CrudPerson operation that will, depending on the type of the message send from the service to it, dispatch the information needed to do the action requested.

For more details you can check the How it works part of this fully documented demo.

5. How to Work With it

This template creates /crud REST web-application on IRIS which implements 4 types of communication: GET, POST, PUT and DELETE aka CRUD operations. These interface works with a sample persistent class Person found in src/python/person/obj.py.

First of all, it is needed to start the 'app.py' situated in src/python/person/app.py using flask.
To do this, go in the app.py file, then to the run and debug window in VSCode and select Python: Flask then run. This will run the app.

5.1. POST request

5.1.1. Testing POST request

Create a POST request, for example in Postman or in RESTer for mozilla, with raw data in JSON like:

{"name":"Elon Musk","title":"CEO","company":"Tesla","phone":"123-123-1233","dob":"1982-01-19"}

Using Content-Type as application/json

Adjust the authorisation if needed - it is basic for container with default login and password for IRIS Community edition container.
Send the POST request to localhost:5000/persons/
This will create a record in the table Sample.Person of IRIS and return the id of the newly added Person

of the POST request to add Elon Musk to the table.

5.1.2. How POST request works

    def create_person(self,request:CreatePersonRequest):
        """
        > Create a new person in the database and return the new person's ID
        
        :param request: The request object that was passed in from the client
        :type request: CreatePersonRequest
        :return: The ID of the newly created person.
        """
    <span class="pl-c"># sqlInsert = 'insert into Sample.Person values (?,?,?,?,?)'</span>
    <span class="pl-c"># iris.sql.exec(sqlInsert,request.person.company,dob,request.person.name,request.person.phone,request.person.title)</span>
    
    <span class="pl-c"># IRIS ORM</span>
    <span class="pl-s1">person</span> <span class="pl-c1">=</span> <span class="pl-s1">iris</span>.<span class="pl-en">cls</span>(<span class="pl-s">'Sample.Person'</span>).<span class="pl-en">_New</span>()
    <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">company</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Company</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
    <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">name</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Name</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
    <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">phone</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Phone</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
    <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">title</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Title</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
    <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">dob</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">DOB</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 

    <span class="pl-v">Utils</span>.<span class="pl-en">raise_on_error</span>(<span class="pl-s1">person</span>.<span class="pl-en">_Save</span>())
    
    <span class="pl-k">return</span> <span class="pl-v">CreatePersonResponse</span>(<span class="pl-s1">person</span>.<span class="pl-en">_Id</span>())</pre></div>

Using IRIS ORM we can create a new Person and save into our database.
5.2. GET requests
5.2.1. Testing GET request
To test GET you need to have some data. You can create it with a POST request.
This REST API exposes two GET requests: all the data and one record.
To get all the data in JSON call:
localhost:5000/persons/all




To request the data for a particular record provide the id in GET request like 'localhost:5000/persons/id', here is an example:
localhost:5000/persons/1

This will return JSON data for the person with ID=1, something like that:
{"name":"Elon Musk","title":"CEO","company":"Tesla","phone":"123-123-1233","dob":"1982-01-19"}
5.2.2. How GET request works
    def get_person(self,request:GetPersonRequest):
        """
        > The function takes a `GetPersonRequest` object, executes a SQL query, and returns a
        `GetPersonResponse` object
        
        :param request: The request object that is passed in
        :type request: GetPersonRequest
        :return: A GetPersonResponse object
        """
        sql_select = """
            SELECT 
                Company, DOB, Name, Phone, Title
            FROM Sample.Person
            where ID = ?
            """
        rs = iris.sql.exec(sql_select,request.id)
        response = GetPersonResponse()
        for person in rs:
            response.person= Person(company=person[0],dob=person[1],name=person[2],phone=person[3],title=person[4])
        return response
<span class="pl-k">def</span> <span class="pl-en">get_all_person</span>(<span class="pl-s1">self</span>,<span class="pl-s1">request</span>:<span class="pl-v">GetAllPersonRequest</span>):
    <span class="pl-s">"""</span>

        > This function returns a list of all the people in the Person table

        

        :param request: The request object that is passed to the service

        :type request: GetAllPersonRequest

        :return: A list of Person objects

        """
    <span class="pl-s1">sql_select</span> <span class="pl-c1">=</span> <span class="pl-s">"""</span>

            SELECT 

                Company, DOB, Name, Phone, Title

            FROM Sample.Person

            """

rs = iris.sql.exec(sql_select)

response = GetAllPersonResponse()

response.persons = list()

for person in rs:

response.persons.append(Person(company=person[0],dob=person[1],name=person[2],phone=person[3],title=person[4]))

return response

This time, using the iris python sql.exec function, we can directly run SQL code inside the IRIS database, gather the information needed and send it back to the API and to the user.
5.3. PUT request
5.3.1. Testing PUT request
PUT request could be used to update the records. This needs to send the similar JSON as in POST request above supplying the id of the updated record in URL.
For example we want to change the record with id=5. Prepare the JSON in raw like following:
{"name":"Jeff Besos","title":"CEO","company":"Amazon","phone":"123-123-1233","dob":"1982-01-19"}

and send the put request to:
localhost:5000/persons/5

5.3.2. How PUT request works
    def update_person(self,request:UpdatePersonRequest):
        """
        > Update a person in the database
        
        :param request: The request object that will be passed to the service
        :type request: UpdatePersonRequest
        :return: UpdatePersonResponse()
        """
    <span class="pl-c"># IRIS ORM</span>
    <span class="pl-k">if</span> <span class="pl-s1">iris</span>.<span class="pl-en">cls</span>(<span class="pl-s">'Sample.Person'</span>).<span class="pl-en">_ExistsId</span>(<span class="pl-s1">request</span>.<span class="pl-s1">id</span>):
        <span class="pl-s1">person</span> <span class="pl-c1">=</span> <span class="pl-s1">iris</span>.<span class="pl-en">cls</span>(<span class="pl-s">'Sample.Person'</span>).<span class="pl-en">_OpenId</span>(<span class="pl-s1">request</span>.<span class="pl-s1">id</span>)
        <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">company</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Company</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
        <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">name</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Name</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
        <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">phone</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Phone</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
        <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">title</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">Title</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
        <span class="pl-k">if</span> (<span class="pl-s1">v</span><span class="pl-c1">:=</span><span class="pl-s1">request</span>.<span class="pl-s1">person</span>.<span class="pl-s1">dob</span>) <span class="pl-c1">is</span> <span class="pl-c1">not</span> <span class="pl-c1">None</span>: <span class="pl-s1">person</span>.<span class="pl-v">DOB</span> <span class="pl-c1">=</span> <span class="pl-s1">v</span> 
        <span class="pl-v">Utils</span>.<span class="pl-en">raise_on_error</span>(<span class="pl-s1">person</span>.<span class="pl-en">_Save</span>())
    
    <span class="pl-k">return</span> <span class="pl-v">UpdatePersonResponse</span>()</pre></div>

Using IRIS ORM we can check if the id leads to a Person, if it does, we can update it using our new information and save it into our database.
5.4. DELETE request
5.4.1. Testing DELETE request
For delete request this REST API expects only the id of the record to delete. E.g. if the id=5 the following DELETE call will delete the record:
localhost:5000/persons/5

5.4.2. How DELETE request works
    def delete_person(self,request:DeletePersonRequest):
        """
        > Delete a person from the database
        
        :param request: The request object that is passed to the service
        :type request: DeletePersonRequest
        :return: The response is being returned.
        """
    <span class="pl-s1">sql_select</span> <span class="pl-c1">=</span> <span class="pl-s">"""</span>

            DELETE FROM Sample.Person as Pers

            WHERE Pers.id = ?

            """

rs = iris.sql.exec(sql_select,request.id)

response = DeletePersonResponse()

return response

This time, using the iris python sql.exec function, we can directly run SQL code inside the IRIS database and delete the person.
6. How to start coding
This repository is ready to code in VSCode with InterSystems plugins.
Open /src/python/person/app.py to change anything on the api.
Open /src/python/person/bo.py to be able to change things related to the internal requests, this is where you can use SQL - it will be compiled in running IRIS docker container.
7. What's inside the repo
7.1. Dockerfile
The simplest dockerfile to start IRIS.
Use the related docker-compose.yml to easily setup additional parametes like port number and where you map keys and host folders.
7.2. .vscode/settings.json
Settings file to let you immedietly code in VSCode with VSCode ObjectScript plugin)
7.3. .vscode/launch.json
Config file if you want to debug with VSCode ObjectScript

Robert Cemper22 September 2022

Strong help to start flask

The docker container builds fine without problems
I added mapping of port 5000 that was referred by the demo
Running the test without using VSCode was bypassed by manual start
I added the required bash_script to my PR
Then the test using Postman was running fine
only GET //localhost:5000/persons/all refused results
but GET //localhost:5000/persons/ did teh trick

Rating

4.5

(1)

iris-python-flask-api-template

What's new in this version

1. intersystems-iris-docker-rest-template

2. Prerequisites

3. Installation

3.1. Installation for development

3.2. Management Portal and VSCode

3.3. Having the folder open inside the container

4. How it works

5. How to Work With it

5.1. POST request

5.1.1. Testing POST request

5.1.2. How POST request works

5.2. GET requests

5.2.1. Testing GET request

5.2.2. How GET request works

5.3. PUT request

5.3.1. Testing PUT request

5.3.2. How PUT request works

5.4. DELETE request

5.4.1. Testing DELETE request

5.4.2. How DELETE request works

6. How to start coding

7. What's inside the repo

7.1. Dockerfile

7.2. .vscode/settings.json

7.3. .vscode/launch.json

Tag version: 1.0.0