refactor: streamline, version, and improve SDK experience

[aeneasr]

BREAKING CHANGE: This change introduces a better SDK. As part of this change, several breaking changes with regards to the SDK have been introduced. We recommend reading this section carefully to understand the changes and how they might affect you.

Before, the SDK was structured into tags public and admin. This stems from the fact that we have two ports in Ory Kratos - one administrative and one public port.

While serves as a good overview when working with Ory Kratos, it does not express:

• What module the API belongs to (e.g. self-service, identity, ...)
• What maturity the API has (e.g. experimental, alpha, beta, ...)
• What version the API has (e.g. v0alpha0, v1beta0, ...)

This patch replaces the current admin and public tags with a versioned approach indicating the maturity of the API used. For example, initializeSelfServiceSettingsForBrowsers would no longer be under the public tag but instead under the v0alpha1 tag:

import {
  Configuration,
- PublicApi
+ V0Alpha1
} from '@ory/kratos-client';

- const kratos = new PublicApi(new Configuration({ basePath: config.kratos.public }));
+ const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.public }));

To avoid confusion when setting up the SDK, and potentially using the wrong endpoints in your codebase and ending up with strange 404 errors, Ory Kratos now redirects you to the correct port, given that serve.(public|admin).base_url are configured correctly. This is a significant improvement towards a more robust API experience!

Further, all administrative functions require, in the Ory SaaS, authorization using e.g. an Ory Personal Access Token. In the open source, we do not know what developers use to protect their APIs. As such, we believe that it is ok to have admin and public functions under one common API and differentiate with an admin prefix. Therefore, the following patches should be made in your codebase:

import { 
- AdminApi, 
+ V0Alpha1,
  Configuration
} from '@ory/kratos-client';

-const kratos = new AdminApi(new Configuration({ basePath: config.kratos.admin }));
+const kratos = new V0Alpha1(new Configuration({ basePath: config.kratos.admin }));

-kratos.createIdentity({
+kratos.adminCreateIdentity({
  schema_id: 'default',
  traits: { /* ... */ }
})

Further, we have introduced a style guide for writing SDKs annotations governing how naming conventions should be chosen.

We also streamlined how credentials are used. We now differentiate between:

• Per-request credentials such as the Ory Session Token / Cookie

  - public getSelfServiceRegistrationFlow(id: string, cookie?: string, options?: any) {}
  + public getSelfServiceSettingsFlow(id: string, xSessionToken?: string, cookie?: string, options?: any) {}
  

• Global credentials such as the Ory (SaaS) Personal Access Token.

  const kratos = new V0Alpha0(new Configuration({ basePath: config.kratos.admin, accessToken: 'some-token' }));
  
  kratosAdmin.adminCreateIdentity({
    schema_id: 'default',
    traits: { /* ... */ },
  });

We hope you enjoy the vastly improved experience! There are still many things that we want to iterate on. For full context, we recommend reading the proposal and discussion around these changes at kratos#1424.

Additionally, the Self-Service Error endpoint was updated. First, the endpoint /self-service/errors is now located at the public port only with the admin port redirecting to it. Second, the parameter ?error was renamed to ?id for better SDK compatibility. Parameter ?error is still working but will be deprecated at some point. Third, the response no longer contains an error array in errors but instead just a single error under error:

{
  "id": "60208346-3a61-4880-96ae-0419cde8fca8",
- "errors": [{
+ "error": {
    "code": 404,
    "status": "Not Found",
    "reason": "foobar",
    "message": "The requested resource could not be found"
- }],
+ },
  "created_at": "2021-07-07T11:20:15.310506+02:00",
  "updated_at": "2021-07-07T11:20:15.310506+02:00"
}

Closes #1424

[codecov]

Codecov Report

Merging #1477 (2be4a8f) into master (24d3afc) will increase coverage by 2.24%.
The diff coverage is 77.14%.

@@            Coverage Diff             @@
##           master    #1477      +/-   ##
==========================================
+ Coverage   71.58%   73.83%   +2.24%     
==========================================
  Files         250      256       +6     
  Lines       10741    12425    +1684     
==========================================
+ Hits         7689     9174    +1485     
- Misses       2427     2628     +201     
+ Partials      625      623       -2     

Impacted Files	Coverage Δ
cmd/identities/validate.go	62.12% <0.00%> (+0.21%)	⬆️
cmd/remote/status.go	0.00% <0.00%> (ø)
cmd/remote/version.go	0.00% <0.00%> (ø)
identity/identity.go	88.46% <ø> (+2.21%)	⬆️
internal/testhelpers/e2e_server.go	92.10% <ø> (+0.67%)	⬆️
internal/testhelpers/errorx.go	100.00% <ø> (ø)
internal/testhelpers/selfservice_login.go	100.00% <ø> (ø)
internal/testhelpers/selfservice_recovery.go	100.00% <ø> (ø)
internal/testhelpers/selfservice_registration.go	100.00% <ø> (ø)
internal/testhelpers/selfservice_settings.go	89.37% <ø> (+0.93%)	⬆️
... and 291 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 24d3afc...2be4a8f. Read the comment docs.