v2 -> v3 transition guide

A transition guide for clients moving over to v3 from v2. If you're new to the API, please skip this page.

We strongly recommend all our clients to switch over and use the latest v3 API. v2 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.

1. Creating a profile
2. Uploading and processing the genome file
3. Generating reports (simple and summary)
4. Generating PDFs

Creating a Profile

Profiles, being an essential part of the SD API, are now moved over to the Profiles section, where we allow all CRUD operations for you to manage your profiles. In v3, we no longer support creation of profiles along with creation of jobs by passing in profile_data field to POST /report-job/profile/. This makes it simpler to manage profiles separately. Once you create a profile, an id is returned in the response, which can later be used at the time of report job creation.

Uploading and Processing the Genome File

In v3, we no longer support uploading your genome file via the /report-job/upload-file/ endpoint, or by passing a file_url at the time of report job creation. Rather, we introduced a new Genome Files section, that allows you to view the metadata of, download and upload your genome files against your profile. In v3, the only way to upload a genome file is to use the genome-file/upload-file endpoint, making the process simpler and less ambiguous.

However, nothing changes with respect to the processing of genome file. If you're creating a report job (or ancestry job) for the first time against a profile, and you have uploaded the temp file against the profile, you have to provide the file_id returned from the genome-file/upload-file at the time of job creation, in the body of the request, to initiate the processing of the genome file, as mentioned under the body params section of the /report-job/ endpoint. To get visibility into the status of your genome file processing, you can query the /genome-file/ list endpoint, that supports filtering genome files by profile_id.

Generating Reports (Simple and Summary)

Report Jobs

Deprecated vs New Endpoints

In v3, we no longer have the duality of endpoints with respect to creating a report job for existing profile vs. for a new profile. Now, every report job mandates the creation of a profile beforehand, using the Profiles API. Therefore, the following endpoints are deprecated in favour of the new endpoints:

Deprecated Endpoints (required passing in profile_data for new profile in request body or profile_id in URL for existing profile)	New Endpoints (requires profile_id to be provided in request body)
/report-job/profile/ and /report-job/profile/{profile_id}/	/report-job/
/report-job/profile/bulk-create/ and /report-job/profile/{profile_id}/bulk-create/	/report-job/bulk-create/
/report-job/profile/generate-all/ and /report-job/profile/{profile_id}/generate-all/	/report-job/generate-all/

Desired Status Field

The old endpoints supported the following options for desired_status at the time of report job creation:

• profile_upserted
• file_processed
• report_generated
• pdf_generated

The new ones only support

• report_generated
• pdf_generated

profile_upserted is deprecated, for the obvious reason that new endpoints mandate creation of profile from the Profiles API.

file_processed is deprecated, because genome file is processed implicitly if you provide the file_id at the time of job creation anyways.

For more details, refer here.

Regenerating Reports

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

Composing Report Detail Page for Simple (Regular) Reports

Composed Profile Report Endpoint

/composed-profile-report/{id}/ is deprecated in favour of the existing endpoint /composed-profile-report/profile/{profile_id}/report/{report_id}/ Now there is only one way to compose a profile report detail page, i.e. by providing the profile_id and report_id combination. There remains no use left for profile_report_id, that was previously provided in /composed-profile-report/{id}/ as the path parameter. The profile_report_id field is still returned in the response for backwards compatibility, but it is deprecated for v3.

Associated Genes

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

Profile Trait

The profile_trait object returned from composed-profile-report endpoint is altered in the following ways:

• score field is deprecated and should not be used. Use outcome_id together with gauge_labels to determine result of report. For more details, refer here.
• Under the nested trait object, 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
• Instead, you can display the result of the report using only the outcome_id and gauge_labels as discussed here. 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 gauge fields listed under the previous point, that are now omitted, based on the type of report, making it difficult for clients to handle all cases and generate the gauges on their frontend.
• If you're still interested in more than just the discrete outcome of the report, and want to display a numeric score for the report, for that we have introduced a new field percentage_or_percentile which is supposed to be used together with trait.statistic_type field. For more details, please refer here.

Profile Report Recommendations

is_relevant field is omitted, and only relevant recommendations are returned.

Other information, like side_effects, how_it_helps and how_to_take is now also included under the nested report_recommendation field.

Composing Report Detail Page for Summary Reports

Child Reports

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

Profile Report Recommendations

In v2, to show the complete detail page of a summary report, including recommendations, you had to rely on information from two additional endpoints other than the composed-profile-report endpoint, namely the /profile-report-recommendation/ and recommendation_id endpoint.

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.

Generating PDFs

The standalone pdf-job endpoints are deprecated in v3.

• To generate health report PDF (for both simple or summary reports), the only option now is to do so using the report-job endpoints, by passing desired_status as pdf_generated. For more details, please refer here.
• To generate ancestry / mtdna PDF reports, the only option now is to do so using the ancestry-job endpoints, by passing the desired_status as pdf_generated. For more details, please refer here.
• To generate lab results PDF, the only option is to use the new lab-pdf-job endpoint. For more details, please refer here.