General Concepts

The FHIR Standard defines itself as 'RESTful', which is based on REST, so that the consistent interoperability is maintained throughout all the RESTful server. The resource structures and interfaces are designed and standardized accordingly with FHIR full Level 3 standard. All the requests and transactions are performed with the server via HTTP requests and responses. The API will also be featured with security consideration including authentication and authorization.

HTTP Requests

All the API requests are in the form of HTTP requests, which comply with the standard of RESTful API, using HTTP methods defined by RFC 2616. Even though FHIR Level 3 standard supports response type of XML and JSON, we would support JSON format only in current stage, except the response for getting CCDA documents.

The request would include these factors: HTTP method, base URL, and parameters. Here's one example:

In this case, the HTTP method is GET. The base URL is https://evalfhir.directmdemail.com/fhir/baseDstu3/Patient. And the parameter concerning this specific resource Patient is family=Newman.

Security and Authentication

SSL/TLS connections would be accepted through an HTTPS connection, which means, all requests to this RESTful API must be made via HTTPS.

Client authentication would be adapted using OAuth 2.0 authorization specified in RFC 6749. Client would need to be directed to the authorization URL. After the user having successfully logged in the API with username and password. An authorization code would be provided to the client. With the authorization code, an access token would also be provided to the application by the resource server. Here is the illustration for the OAuth 2.0 procedure.

The sample endpoint URLs should be like these, for different authorization purposes.

Endpoint	URL
Authorization	https://evalfhir.directmdemail.com/oauth2/authorize
Token	https://evalfhir.directmdemail.com/oauth2/accessToken

Response Codes

The RESTful API would reply clients with response codes to indicate the result status of the corresponding API requests.

Response Code	Description
200	Okay - Successful Requests
400	Bad Request - The Request is Missing Information or is Malformed
401	Not Authorized - Authorization is Required
403	Forbidden - The Request is Valid, but the Server is Refusing Action
404	Not Found - The Requested Resource Cannot be Found
500	Internal Server Error - A problem Occurs in Our Server

Exception and Exception Handling

General RESTful API calls exception codes could be found above.

Otherwise, an resource object OperationOutcome, defined in https://www.hl7.org/fhir/operationoutcome.html, would be returned as the feedback of the exception. Detailed information like the severity of the exception, which type is the exception, as well as the detailed diagnostic reason.

For example, if a developer is trying to access an non-existing resource type.

Request:

Outcome:

        {
    "resourceType": "OperationOutcome",
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><tr><td style=\"font-weight: bold;\">ERROR</td><td>[]</td><td><pre>Unknown resource type 'Patients' - Server knows how to handle: [Appointment, Account, ReferralRequest, DocumentManifest, MessageDefinition, Goal, Endpoint, EnrollmentRequest, Consent, CapabilityStatement, Measure, Medication, ResearchSubject, Subscription, DocumentReference, GraphDefinition, ImagingManifest, Parameters, MeasureReport, PractitionerRole, RelatedPerson, SupplyRequest, Practitioner, ExpansionProfile, Slot, Contract, Person, RiskAssessment, Group, PaymentNotice, Organization, CareTeam, ImplementationGuide, ImagingStudy, DeviceComponent, FamilyMemberHistory, ChargeItem, Encounter, Substance, SearchParameter, ServiceDefinition, ActivityDefinition, Communication, Linkage, DeviceUseStatement, RequestGroup, DeviceRequest, MessageHeader, BodySite, ImmunizationRecommendation, Provenance, Task, Questionnaire, ExplanationOfBenefit, ResearchStudy, Specimen, AllergyIntolerance, CarePlan, StructureDefinition, EpisodeOfCare, OperationOutcome, Procedure, List, ConceptMap, OperationDefinition, ValueSet, Immunization, MedicationRequest, Device, VisionPrescription, Media, EligibilityResponse, ProcedureRequest, Sequence, DeviceMetric, CodeSystem, Flag, AppointmentResponse, StructureMap, AdverseEvent, GuidanceResponse, Observation, MedicationAdministration, EnrollmentResponse, Binary, Library, MedicationStatement, CommunicationRequest, TestScript, Basic, TestReport, ClaimResponse, EligibilityRequest, ProcessRequest, MedicationDispense, DiagnosticReport, HealthcareService, DataElement, NutritionOrder, AuditEvent, PaymentReconciliation, Condition, Composition, DetectedIssue, Bundle, CompartmentDefinition, Patient, Coverage, QuestionnaireResponse, ProcessResponse, NamingSystem, Schedule, SupplyDelivery, ClinicalImpression, PlanDefinition, Claim, Location]</pre></td>\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t</tr>\n\t\t</table>\n\t</div>"
    },
    "issue": [
        {
        "severity": "error",
        "code": "processing",
        "diagnostics": "Unknown resource type 'Patients' - Server knows how to handle: [Appointment, Account, ReferralRequest, DocumentManifest, MessageDefinition, Goal, Endpoint, EnrollmentRequest, Consent, CapabilityStatement, Measure, Medication, ResearchSubject, Subscription, DocumentReference, GraphDefinition, ImagingManifest, Parameters, MeasureReport, PractitionerRole, RelatedPerson, SupplyRequest, Practitioner, ExpansionProfile, Slot, Contract, Person, RiskAssessment, Group, PaymentNotice, Organization, CareTeam, ImplementationGuide, ImagingStudy, DeviceComponent, FamilyMemberHistory, ChargeItem, Encounter, Substance, SearchParameter, ServiceDefinition, ActivityDefinition, Communication, Linkage, DeviceUseStatement, RequestGroup, DeviceRequest, MessageHeader, BodySite, ImmunizationRecommendation, Provenance, Task, Questionnaire, ExplanationOfBenefit, ResearchStudy, Specimen, AllergyIntolerance, CarePlan, StructureDefinition, EpisodeOfCare, OperationOutcome, Procedure, List, ConceptMap, OperationDefinition, ValueSet, Immunization, MedicationRequest, Device, VisionPrescription, Media, EligibilityResponse, ProcedureRequest, Sequence, DeviceMetric, CodeSystem, Flag, AppointmentResponse, StructureMap, AdverseEvent, GuidanceResponse, Observation, MedicationAdministration, EnrollmentResponse, Binary, Library, MedicationStatement, CommunicationRequest, TestScript, Basic, TestReport, ClaimResponse, EligibilityRequest, ProcessRequest, MedicationDispense, DiagnosticReport, HealthcareService, DataElement, NutritionOrder, AuditEvent, PaymentReconciliation, Condition, Composition, DetectedIssue, Bundle, CompartmentDefinition, Patient, Coverage, QuestionnaireResponse, ProcessResponse, NamingSystem, Schedule, SupplyDelivery, ClinicalImpression, PlanDefinition, Claim, Location]"
        }
    ]
}