Version 3 by tomchristie · Pull Request #156 · core-api/python-client (original) (raw)

Core API started off as an attempt to address hypermedia - how to build free-form documents that contain both data and links. We're able to use it for API schemas, (and representations such as OpenAPI & RAML) because those happen to be documents that only contain links.

Practically I think that having the tooling focus specifically on schema representations is going to be a better way forward. That's where the vast majority of the need actually lies, and I think we can do a better job of pushing forward schema-driven client libs, schema-driven documentation, and other tooling, if we restrict ourselves just to that.

I'd also like to see us build in proper typing support, currently in coreschema, so that we can have calls that actually return data types that look like we expect, and be able to eg. instantiate data types in the client, and immediately get client-side validation errors on incorrect values.

Going to try to start to work towards that incrementally, perhaps eventually coupled with a REST framework 3.8 release.

Drop deprecated arguments:

• Drop transform on Links and remove inplace transformations.
• Drop action and 'encoding' parameters on the Client, in favor of the general purpose overrides
• Drop credentials on HTTPTransport in favor of auth.
• Drop request_callback/response_callback on HTTPTransport in favor of custom sessions.

Remove data from documents:

• Drop Array.
• Include typesys, and drop coreschema package.
• Include built-in codec for OpenAPI.

TODO:

• Use JSON style for OpenAPI (provide YAML as a third party package).
• Drop Document.media_type. Add Document.version.
• Review any possible breaking changes.
• Review cli
• Drop itypes.
• action -> method?
• Nullable support in typesys.
• Revisit documentation.
• Sections
• Make Link urls relative to Document urls
• Split schema codecs from client codecs.
• Use client = Client(document), not client.action(document, [...])
• Review JS client
• Review OpenAPI support (In particular support references.)

Later:

• Consider refactoring repr/str, and dropping DisplayCodec/PythonCodec.
• Support reusable type refs in documents.
• Review CoreJSON
• Responses and response schemas

Initial proposal for Documents, something along these lines:

Document

• title: string
• description: string
• url: string
• version: string
• sections: [Section] Note: replaces general 'content' with more structured sections

Section

• id: string, required, "[a-zA-Z_][a-zA-Z0-9_]*" or ""
• title: string
• description: string
• links: [Link]

Link

• id: string, required, "[a-zA-Z_][a-zA-Z0-9_]*"
• title: string
• description: string
• url: string
• method: string
• encoding: string
• fields: [Field]

Field

• id: string, required, "[a-zA-Z_][a-zA-Z0-9_]*"
• title: string
• description: string
• location: string
• required: boolean
• schema: Schema
• example: Any