v1 -> v3 transition guide

We strongly recommend all our clients to switch over and use the latest v3 API. v1 endpoints still work, but are deprecated, and will soon no longer be supported. The purpose of this document is to make the transition process easier.

v3 makes the SD API much easier to use, with endpoints split into different sections based on the entities they interact with.

The changes in the following four flows are discussed in this document.

Creating a profile
Uploading and processing the genome file
Generating reports (simple and summary)
Generating PDFs

Creating a Profile

All the CRUD operations for profiles are still supported, with the URL being updated from /profiles/profile/ to /b2b-integrations/profile. For more details, please refer to the Profiles API.

Generating Reports, Uploading and Processing Genome File & Generating PDFs

Listing Reports Provided by SD

To get the latest summary of health reports offered by SelfDecode, refer to the GET /report-summary/ endpoint.

Report Jobs

In v3, we have introduced report jobs that automate the following

Report generation
Genome file processing
PDF generation for the report

For more details, please refer here.

Composing Report Detail Page for Simple Reports

Instead of having to call a series of endpoints to get all the required information, like the profile report recommendations and profile trait to generate a report detail page, in v3, the process to compose a report detail page, for both simple reports and summary reports has been reduced to calling a single endpoint composed-profile-report after generating the report via the report job.

Endpoints required in v1 to compose a profile report	Endpoint required in v3 to compose a profile report
`/report/` `/profile-report/` `profile-report-recommendation` `/profile-trait/`	`/composed-profile-report/`

For more details regarding the composed-profile-report endpoint, please refer here.

The new endpoint aggregates all the fields previously returned from various endpoints into the response of the single composed-profile-report endpoint, and introduces some new information too. Below, the changes to those fields are discussed.

Profile Trait

For complete details about the new profile_trait object, now returned as part of the response of the composed-profile-report endpoint, please refer to the Profile Trait section in the new v3 docs.

This section lists how the new version of profile_trait differs from what you would get via v1. Before diving into that list, one major difference that we now have compared to v1, is that we've let go of gauges to display the final result of the report, and have switched over to discrete results (outcomes) for reports, with every report (except for aggregate reports) having an outcome of its own, that represent your category of risk - for example "Lower", "Typical", and "Higher".

Let's now have a look at other differences in profile_trait, including how to display outcomes:

profile_report_id field is deprecated, and should no longer be used for any purpose.
The redundant trait_id field is removed, which can be obtained from trait.id
user_feedback field is omitted
score field is deprecated and should not be used. Other outcome fields namely scenario_id, scenario_percentage, and matched_case are removed. Instead, two new fields, outcome_id and percentage_or_percentile are returned. Use outcome_id together with gauge_labels to determine and graphically display the discrete result (outcome) of report. For more details, refer to the new Profile Trait section, down till the Icons to Represent Result of Report subsection. This simplifies the process by standardising how the report outcome should look like for reports of all types, except for combined reports, which are discussed below. Previously, we had lots of variations in the now omitted gauge fields listed below, based on the type of report, making it difficult for clients to handle all cases and generate the graphical gauges on their frontend.
If you're interested in more than just the discrete outcome of the report, and want to display a numeric score for the report, use the new percentage_or_percentile field together with trait.statistic_type field. percentage_or_percentile field can be considered a combination of the two old fields score and scenario_percentage. For more details, please refer to the Report Score subsection.
Under the nested trait object
- show_percentile field is omitted. Instead, if percentage_or_percentile is null, it means the same as show_percentile being false and the numeric score should be hidden.
- the following fields have been removed, that were previously returned to generate various types of gauges reflecting the result of the report:
  - gauge_title
  - gauge_subtitle
  - gauge_type
  - gauge_range_type
  - gauge_coloring
  - gauge_direction
  - gauge_num_of_divisions
- under gauge_labels, the following fields are omitted as they are no longer needed:
  - sub_case
  - score_from
  - score_to
  - scenario_id
- feedback_choices andfeedback_question fields are omitted
- genetic_intro and disclaimer fields are also omitted

Profile Report Recommendations

For complete details about the new profile_report_recommendations object, now returned as part of the response of the composed-profile-report endpoint, please refer to the Profile Report Recommendation section in the new v3 docs.

This section explains the differences between recommendations returned in v3 compared to the old endpoint:

Recommendations are now returned pre-sorted, by impact.
profile_report_id is now a deprecated field and should not be used.
is_relevant field is omitted, and only relevant recommendations are returned.
total_score is omitted
User feedback fields was_useful and user_hidden are omitted
translation_exists field is omitted
The redundant report_recommendation_id field is omitted, which can be obtained from report_recommendation_id.id
From the nested report_recommendation, the following fields are omitted:
- conflicting_slugs
- bad_interactions
- impact (was redundant, now only present in the parent object)
- evidence (was redundant, now only present in the parent object)
- visible_to_user_types
- dose_value
- dose_unit
- hide_impact_evidence
- initial_score

Associated Genes

The GET composed-profile-report endpoint introduces a new field, associated_genes For more details, refer here.

Composing Report Detail Page for Summary Reports

Child Reports

A new field, child_reports is returned in the same composed-profile-report endpoint for summary reports, allowing you to display the outcome details of the summary report's sub-reports using information from just one endpoint, without having to redundantly call the endpoints for each sub-report. For more details, please refer here.

Profile Report Recommendations

In v1, to show the complete detail page of a summary report, including recommendations of its sub-reports, you had to rely on information from additional endpoints.

Now, all that information is returned in the profile-report-recommendations and sorted_recommendation_ids field of the response of composed-profile-report endpoint. For more details, refer here.

Pie Charts for Combined Report Outcomes

Nothing changes here, but v3 docs offer a better explanation on how to generate pie charts for combined report outcomes. Please refer here for more details.

Regenerating Reports

We have added endpoints to allow regeneration of reports. Refer here for more details.