FHIR APIs | FHIR® tutorials

Working with APIs for FHIR

If you're a developer, or just someone interested in coding with FHIR, then this is the page for you to read! In this tutorial we'll walk you through doing all of the tutorials you've been doing with Postman programmatically.

This tutorial requires technical knowledge to do! If you're not technically minded, you can still learn FHIR by doing other tutorials on this website.

Click the appropriate button below depending on which programming language you are interested in. This will help this web site display the examples most relevant to your choice.

Работа с API для FHIR

Если вы разработчик или просто хотите писать код для работы с FHIR, эта страница для вас! В этом уроке мы покажем, как программно выполнить всё то, что вы делали в предыдущих уроках с помощью Postman.

Для этого урока нужны технические знания! Если вы не программист, вы всё равно можете изучать FHIR с помощью других уроков на этом сайте.

Нажмите кнопку ниже, соответствующую интересующему вас языку программирования. Тогда сайт будет показывать примеры, наиболее подходящие для вашего выбора.

Step 1: Setup Шаг 1: Подготовка

FHIR provides some official API code libraries in Java and .NET to help you work with the standard.

They are:

Java

HAPI FHIR library: To get started with HAPI, add the dependency via Maven or Gradle - or download the library from the releases page. For R4, include all non-hapi jars in your classpath, and the following HAPI jars: hapi-fhir-base, hapi-fhir-structures-r4, hapi-fhir-validation-resources-r4.

To run the Java examples you need a Java Development Kit (JDK); current HAPI FHIR releases require JDK 17 or newer.

Microsoft .Net

FHIR .NET SDK: The simplest way to get started with the .NET SDK is to search for it in the NuGet package manager built into Visual Studio. Right click your Solution and select 'Manage NuGet Packages' and then search for and install 'Hl7.Fhir.R4'. You can find a C# project here on GitHub that contains C# examples.

Для FHIR существуют официальные библиотеки API на Java и .NET, которые помогают работать со стандартом.

Вот они:

Java

Библиотека HAPI FHIR: чтобы начать работу с HAPI, добавьте зависимость через Maven или Gradle — или скачайте библиотеку со страницы релизов. Для R4 добавьте в classpath все jar-файлы, не относящиеся к HAPI, а также следующие jar-файлы HAPI: hapi-fhir-base, hapi-fhir-structures-r4, hapi-fhir-validation-resources-r4.

Актуальные версии HAPI FHIR требуют Java 17 или новее.

Microsoft .NET

FHIR .NET SDK: проще всего начать работу с .NET SDK, найдя его в менеджере пакетов NuGet, встроенном в Visual Studio. Щёлкните правой кнопкой мыши по решению (Solution), выберите 'Manage NuGet Packages', затем найдите и установите пакет 'Hl7.Fhir.R4'. Проект с примерами на C# можно найти на GitHub здесь.

Step 2: Create a basic Patient Шаг 2: Создание простого ресурса Patient

Upon creating a new project, you'll see a new blank class not much different from this:

Создав новый проект, вы увидите пустой класс примерно такого вида:

C# Java

using System;
using System.Collections.Generic;

namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
       // write your code here
    }
  }
}

package com.myhotcompany;

public class Main {

    public static void main(String[] args) {
	// write your code here
    }
}

Create a basic Patient resource and populate it with some information. Running this code will print the resource as JSON for you:

Создайте простой ресурс Patient и заполните его какими-нибудь данными. При запуске этот код выведет ресурс в формате JSON:

C# Java

using System;
using System.Collections.Generic;

namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      var MyPatient = new Hl7.Fhir.Model.Patient();

      //Patient's Name
      var PatientName = new Hl7.Fhir.Model.HumanName();
      PatientName.Use = Hl7.Fhir.Model.HumanName.NameUse.Official;
      PatientName.Prefix = new string[] { "Mr" };
      PatientName.Given = new string[] { "Sam" };
      PatientName.Family = "Fhirman";
      MyPatient.Name = new List<Hl7.Fhir.Model.HumanName>();
      MyPatient.Name.Add(PatientName);

      //Patient Identifier
      var PatientIdentifier = new Hl7.Fhir.Model.Identifier();
      PatientIdentifier.System = "http://ns.electronichealth.net.au/id/hi/ihi/1.0";
      PatientIdentifier.Value = "8003608166690503";
      MyPatient.Identifier = new List<Hl7.Fhir.Model.Identifier>();
      MyPatient.Identifier.Add(PatientIdentifier);

      Console.WriteLine("Press any key to serialise Resource to the console as JSON.");
      Console.ReadKey();
      Console.WriteLine("");
      try
      {
        //attempt to serialize the resource
        string json = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToJson(MyPatient);
        Console.Write(json);
        Console.WriteLine("");
        Console.WriteLine("");
      }
      catch (Exception Exec)
      {
        Console.Write("Error message: " + Exec.Message);
      }
      Console.Write("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import org.hl7.fhir.dstu3.model.HumanName;
import org.hl7.fhir.dstu3.model.Patient;

import java.io.IOException;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see https://hapifhir.io/hapi-fhir/docs/getting_started/introduction.html
        FhirContext ctx = FhirContext.forDstu3();

        Patient patient = new Patient();

        // you can use the Fluent API to chain calls
        // see https://hapifhir.io/hapi-fhir/docs/model/working_with_resources.html
        patient.addName().setUse(HumanName.NameUse.OFFICIAL)
                .addPrefix("Mr").addFamily("Fhirman").addGiven("Sam");
        patient.addIdentifier()
                .setSystem("http://ns.electronichealth.net.au/id/hi/ihi/1.0")
                .setValue("8003608166690503");

        System.out.println("Press Enter to serialise Resource to the console as JSON.");
        System.in.read();

        // create a new JSON parser and serialize our Patient object with it
        String encoded = ctx.newJsonParser().setPrettyPrint(true)
                .encodeResourceToString(patient);

        System.out.println(encoded);

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Once run, you should see something like this:

После запуска вы увидите примерно следующее:

If your IDE supports code completion, try using it to explore the Patient resource and populate it with some information such as the gender, birthday and phone number. Otherwise, consult the FHIR Patient page to see what you can populate your resource with (Javadoc is also available).

Если ваша IDE поддерживает автодополнение кода, попробуйте с его помощью изучить ресурс Patient и добавить в него другие данные, например пол, дату рождения и номер телефона. Если нет, загляните на страницу FHIR Patient, чтобы узнать, чем можно заполнить ресурс (также доступна документация Javadoc).

Step 3: Upload your basic Patient Шаг 3: Загрузка ресурса Patient на сервер

Now that we can create a simple resource, let's upload it to a FHIR server:

Теперь, когда мы умеем создавать простой ресурс, давайте загрузим его на FHIR-сервер:

C# Java

using System;
using System.Collections.Generic;

namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      //The fhir server end point address
      string ServiceRootUrl = "https://hapi.fhir.org/baseDstu3";

      //Create a patient resource instance
      var MyPatient = new Hl7.Fhir.Model.Patient();

      //Patient's Name
      var PatientName = new Hl7.Fhir.Model.HumanName();
      PatientName.Use = Hl7.Fhir.Model.HumanName.NameUse.Official;
      PatientName.Prefix = new string[] { "Mr" };
      PatientName.Given = new string[] { "Sam" };
      PatientName.Family = "Fhirman" ;
      MyPatient.Name = new List<Hl7.Fhir.Model.HumanName>();
      MyPatient.Name.Add(PatientName);

      //Patient Identifier
      var PatientIdentifier = new Hl7.Fhir.Model.Identifier();
      PatientIdentifier.System = "http://ns.electronichealth.net.au/id/hi/ihi/1.0";
      PatientIdentifier.Value = "8003608166690503";
      MyPatient.Identifier = new List<Hl7.Fhir.Model.Identifier>();
      MyPatient.Identifier.Add(PatientIdentifier);

      //Create a client to send to the server at a given endpoint.
      var FhirClient = new Hl7.Fhir.Rest.FhirClient(ServiceRootUrl);

      // increase timeouts since the server might be powered down
      FhirClient.Timeout = (60 * 1000);

      Console.WriteLine("Press any key to send to server: " + ServiceRootUrl);
      Console.ReadKey();
      try
      {
        //Attempt to send the resource to the server endpoint
        Hl7.Fhir.Model.Patient ReturnedPatient = FhirClient.Create<Hl7.Fhir.Model.Patient>(MyPatient);
        Console.WriteLine(string.Format("Resource is available at: {0}", ReturnedPatient.Id));
        Console.WriteLine();
        Console.WriteLine("This is what we sent up: ");
        Console.WriteLine();
        string json = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToJson(MyPatient);
        Console.WriteLine(json);
        Console.WriteLine();
        Console.WriteLine("This is what we received back: ");
        Console.WriteLine();
        json = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToJson(ReturnedPatient);
        Console.WriteLine(json);
        Console.WriteLine();
      }
      catch (Hl7.Fhir.Rest.FhirOperationException FhirOpExec)
      {
        //Process any Fhir Errors returned as OperationOutcome resource
        Console.WriteLine();
        Console.WriteLine("An error message: " + FhirOpExec.Message);
        Console.WriteLine();
        string json = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToJson(FhirOpExec.Outcome);
        Console.WriteLine(json);
      }
      catch (Exception GeneralException)
      {
        Console.WriteLine();
        Console.WriteLine("An error message: " + GeneralException.Message);
        Console.WriteLine();
      }
      Console.WriteLine("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.parser.DataFormatException;
import ca.uhn.fhir.parser.IParser;
import ca.uhn.fhir.rest.api.MethodOutcome;
import ca.uhn.fhir.rest.client.IGenericClient;
import org.hl7.fhir.dstu3.model.*;

import java.io.IOException;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see https://hapifhir.io/hapi-fhir/docs/getting_started/introduction.html
        FhirContext ctx = FhirContext.forDstu3();
        String serverBaseUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";

        Patient ourPatient = new Patient();

        // you can use the Fluent API to chain calls
        // see https://hapifhir.io/hapi-fhir/docs/model/working_with_resources.html
        ourPatient.addName().setUse(HumanName.NameUse.OFFICIAL)
                .addPrefix("Mr").addFamily("Fhirman").addGiven("Sam");
        ourPatient.addIdentifier()
                .setSystem("http://ns.electronichealth.net.au/id/hi/ihi/1.0")
                .setValue("8003608166690503");

        // increase timeouts since the server might be powered down
        // see https://hapifhir.io/hapi-fhir/docs/client/client_configuration.html
        ctx.getRestfulClientFactory().setConnectTimeout(60 * 1000);
        ctx.getRestfulClientFactory().setSocketTimeout(60 * 1000);

        // create the RESTful client to work with our FHIR server
        // see https://hapifhir.io/hapi-fhir/docs/client/generic_client.html
        IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);

        System.out.println("Press Enter to send to server: " + serverBaseUrl);
        System.in.read();

        try {
            // send our resource up - result will be stored in 'outcome'
            // see https://hapifhir.io/hapi-fhir/docs/client/generic_client.html#create-type
            MethodOutcome outcome = client.create()
                    .resource(ourPatient)
                    .prettyPrint()
                    .encodedJson()
                    .execute();

            IdType id = (IdType) outcome.getId();
            System.out.println("Resource is available at: " + id.getValue());

            IParser jsonParser = ctx.newJsonParser().setPrettyPrint(true);
            Patient receivedPatient = (Patient) outcome.getResource();
            System.out.println("This is what we sent up: \n"
                    + jsonParser.encodeResourceToString(ourPatient)
                    + "\n\nThis is what we received: \n"
                    + jsonParser.encodeResourceToString(receivedPatient));
        } catch (DataFormatException e) {
            System.out.println("An error occurred trying to upload:");
            e.printStackTrace();
        }

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Comparing the resource that we sent up to the resource we received back, you'll notice that the server generated a basic narrative for us from the data available and also added its logical ID

Сравнив отправленный ресурс с ресурсом, полученным в ответ, вы заметите, что сервер сгенерировал для нас простое текстовое представление (narrative) на основе имеющихся данных, а также присвоил ресурсу логический ID.

Step 4: Search for a resource Шаг 4: Поиск ресурса

Now that you've uploaded a resource, try searching for it. Remember that you'll get a bundle back with many entries, one resource per entry.

Теперь, когда вы загрузили ресурс, попробуйте его найти. Помните, что в ответ вы получите Bundle с множеством записей (entry) — по одному ресурсу в каждой.

C# Java

using System;
using System.Collections.Generic;

namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      //The fhir server end point address
      string ServiceRootUrl = "https://hapi.fhir.org/baseDstu3";
      //Create a client to send to the server at a given endpoint.
      var FhirClient = new Hl7.Fhir.Rest.FhirClient(ServiceRootUrl);
      // increase timeouts since the server might be powered down
      FhirClient.Timeout = (60 * 1000);

      Console.WriteLine("Press any key to send to server: " + ServiceRootUrl);
      Console.WriteLine();
      Console.ReadKey();
      try
      {
        //Attempt to send the resource to the server endpoint
        Hl7.Fhir.Model.Bundle ReturnedSearchBundle = FhirClient.Search<Hl7.Fhir.Model.Patient>(new string[] { "family=Fhirman" });
        Console.WriteLine(string.Format("Found: {0} Fhirman patients.", ReturnedSearchBundle.Total.ToString()));
        Console.WriteLine("Their logical IDs are:");
        foreach (var Entry in ReturnedSearchBundle.Entry)
        {
          Console.WriteLine("ID: " + Entry.Resource.Id);
        }
        Console.WriteLine();
      }
      catch (Hl7.Fhir.Rest.FhirOperationException FhirOpExec)
      {
        //Process any Fhir Errors returned as OperationOutcome resource
        Console.WriteLine();
        Console.WriteLine("An error message: " + FhirOpExec.Message);
        Console.WriteLine();
        string json = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToJson(FhirOpExec.Outcome);
        Console.WriteLine(json);
      }
      catch (Exception GeneralException)
      {
        Console.WriteLine();
        Console.WriteLine("An error message: " + GeneralException.Message);
        Console.WriteLine();
      }
      Console.WriteLine("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.model.primitive.IdDt;
import ca.uhn.fhir.rest.client.IGenericClient;
import org.hl7.fhir.dstu3.model.*;

import java.io.IOException;
import java.util.List;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see https://hapifhir.io/hapi-fhir/docs/getting_started/introduction.html
        FhirContext ctx = FhirContext.forDstu3();
        String serverBaseUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";

        // increase timeouts since the server might be powered down
        // see https://hapifhir.io/hapi-fhir/docs/client/client_configuration.html
        ctx.getRestfulClientFactory().setConnectTimeout(60 * 1000);
        ctx.getRestfulClientFactory().setSocketTimeout(60 * 1000);

        // create the RESTful client to work with our FHIR server
        // see https://hapifhir.io/hapi-fhir/docs/client/generic_client.html
        IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);

        System.out.println("Press Enter to send to server: " + serverBaseUrl);
        System.in.read();

        try {
            // perform a search for Patients with last name 'Fhirman'
            // see https://hapifhir.io/hapi-fhir/docs/client/generic_client.html#search-by-type
            Bundle response = client.search()
                    .forResource(Patient.class)
                    .where(Patient.FAMILY.matches().values("Fhirman"))
                    .returnBundle(Bundle.class)
                    .execute();

            System.out.println("Found " + response.getTotal()
                    + " Fhirman patients. Their logical IDs are:");
            response.getEntry().forEach((entry) -> {
                // within each entry is a resource - print its logical ID
                System.out.println(entry.getResource().getIdElement().getIdPart());
            });
        } catch (Exception e) {
            System.out.println("An error occurred trying to search:");
            e.printStackTrace();
        }

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Step 5: Run an operation Шаг 5: Выполнение операции

Lastly, let's execute an operation on the server. A simple operation we can do is the Patient/$everything - this'll fetch us the Patient resource and all related resources to it.

Firstly, lets upload the sample Patient we've explored before in the Patient with References tutorial:

Напоследок выполним операцию на сервере. Простая операция, с которой можно начать, — Patient/$everything: она вернёт ресурс Patient и все связанные с ним ресурсы.

Сначала загрузим пример пациента, который мы уже рассматривали в уроке Пациент со ссылками:

Now we can run a query on the operation to get a Bundle with the Patient and associated resources. Here's how it looks in code. Make sure to update MY_PATIENT_ID with (press Upload first).

Теперь можно вызвать операцию и получить Bundle с ресурсом Patient и связанными с ним ресурсами. Вот как это выглядит в коде. Не забудьте заменить MY_PATIENT_ID на (сначала нажмите Загрузить).

C# Java

using System;
using System.Collections.Generic;

namespace SimpleFhir
{
  class Program
  {
    static void Main(string[] args)
    {
      //The fhir server end point address
      string ServiceRootUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";
      //Create a client to send to the server at a given endpoint.
      var FhirClient = new Hl7.Fhir.Rest.FhirClient(ServiceRootUrl);
      // increase timeouts since the server might be powered down
      FhirClient.Timeout = (60 * 1000);

      Console.WriteLine("Press any key to send to server: " + ServiceRootUrl);
      Console.WriteLine();
      Console.ReadKey();
      try
      {
        //Attempt to send the resource to the server endpoint
        UriBuilder UriBuilderx = new UriBuilder(ServiceRootUrl);
        UriBuilderx.Path = "Patient/MY_PATIENT_ID";
        Hl7.Fhir.Model.Resource ReturnedResource = FhirClient.InstanceOperation(UriBuilderx.Uri, "everything");

        if (ReturnedResource is Hl7.Fhir.Model.Bundle)
        {
          Hl7.Fhir.Model.Bundle ReturnedBundle = ReturnedResource as Hl7.Fhir.Model.Bundle;
          Console.WriteLine("Received: " + ReturnedBundle.Total + " results, the resources are: ");
          foreach (var Entry in ReturnedBundle.Entry)
          {
            Console.WriteLine(string.Format("{0}/{1}",Entry.Resource.TypeName, Entry.Resource.Id));
          }
        }
        else
        {
          throw new Exception("Operation call must return a bundle resource");
        }
        Console.WriteLine();

      }
      catch (Hl7.Fhir.Rest.FhirOperationException FhirOpExec)
      {
        //Process any Fhir Errors returned as OperationOutcome resource
        Console.WriteLine();
        Console.WriteLine("An error message: " + FhirOpExec.Message);
        Console.WriteLine();
        string json = Hl7.Fhir.Serialization.FhirSerializer.SerializeResourceToJson(FhirOpExec.Outcome);
        Console.WriteLine(json);
      }
      catch (Exception GeneralException)
      {
        Console.WriteLine();
        Console.WriteLine("An error message: " + GeneralException.Message);
        Console.WriteLine();
      }
      Console.WriteLine("Press any key to end.");
      Console.ReadKey();
    }
  }
}

package com.myhotcompany;

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.rest.client.IGenericClient;
import ca.uhn.fhir.rest.client.interceptor.LoggingInterceptor;
import org.hl7.fhir.dstu3.model.*;

import java.io.IOException;

public class Main {

    public static void main(String[] args) throws IOException {
        // context - create this once, as it's an expensive operation
        // see https://hapifhir.io/hapi-fhir/docs/getting_started/introduction.html
        FhirContext ctx = FhirContext.forDstu3();
        String serverBaseUrl = "http://sqlonfhir-stu3.azurewebsites.net/fhir";

        // increase timeouts since the server might be powered down
        // see https://hapifhir.io/hapi-fhir/docs/client/client_configuration.html
        ctx.getRestfulClientFactory().setConnectTimeout(60 * 1000);
        ctx.getRestfulClientFactory().setSocketTimeout(60 * 1000);

        // create the RESTful client to work with our FHIR server
        // see https://hapifhir.io/hapi-fhir/docs/client/generic_client.html
        IGenericClient client = ctx.newRestfulGenericClient(serverBaseUrl);

        client.registerInterceptor(new LoggingInterceptor(true));

        System.out.println("Press Enter to send to server: " + serverBaseUrl);
        System.in.read();

        try {
            // Invoke $everything on our Patient
            // See https://hapifhir.io/hapi-fhir/docs/client/generic_client.html#extended-operations
            Parameters outParams = client
                    .operation()
                    .onInstance(new IdType("Patient", "MY_PATIENT_ID"))
                    .named("$everything")
                    .withNoParameters(Parameters.class) // No input parameters
                    .execute();

            // FHIR normally returns a 'Parameters' resource to an operation, but
            // in case of a single resource response, it just returns the resource
            // itself. This is why it seems that we have to fish a Bundle out of the
            // resulting Params result - HAPI needs to update for the FHIR shortcut
            Bundle result = (Bundle) outParams.getParameterFirstRep().getResource();

            System.out.println("Received " + result.getTotal()
                    + " results. The resources are:");
            result.getEntry().forEach((entry) -> {
                Resource resource = entry.getResource();
                System.out.println(resource.getResourceType() + "/"
                        + resource.getIdElement().getIdPart());
            });
        } catch (Exception e) {
            System.out.println("An error occurred trying to run the operation:");
            e.printStackTrace();
        }

        System.out.println("Press Enter to end.");
        System.in.read();
    }
}

Try running the code and you should see the same IDs for related resources as on this page:

Запустите код — вы должны увидеть те же ID связанных ресурсов, что и на этой странице:

Patient/(press Upload first)(сначала нажмите Загрузить)

Encounter/(press Upload first)(сначала нажмите Загрузить)

Observation/(press Upload first)(сначала нажмите Загрузить)

Observation/(press Upload first)(сначала нажмите Загрузить)

DiagnosticReport/(press Upload first)(сначала нажмите Загрузить)

That's about it for the basics! Happy coding. Check out the HAPI documentation if you're using Java for more as well.

Вот и всё, что касается основ! Удачи в программировании. Если вы пишете на Java, загляните также в документацию HAPI — там вы найдёте больше информации.