8e8e0dabdf
* Add DA_Internal_Interface to convertTypeDef exclusion check * Move desugared types/values for interface views into DA.Internal.Desugar * Convert viewtype and view method declarations * Typecheck view types and view declarations * Add unit viewtypes to InterfaceChoiceCollision tests * Add unit viewtypes to more compiler/damlc tests * Modify empty interfaces/implements to have viewtypes/views * Add unit viewtypes to remaining Interface tests * Test for error thrown when viewtype not specified * Fix daml-lf/ interface tests to use new syntax / unit views * Add placeholder view of type Unit to TestInterfaces CHANGELOG_BEGIN CHANGELOG_END * Fix typescript interface tests with unit viewtype * Add unit viewtype to Java & Scala codegen * Add unit viewtype to triggers tests interface * Add unit viewtypes to ledger/test-common * Add unit viewtypes to ledger-service/http-json * Fix some damlc tests * Use viewtype syntax in InterfaceViewNonSerializable test * Remove HasInferfaceView instances in convertBind * Add unit view to QualifiedInterface.daml test * Generate HasInterfaceView instances in DataDependencies * Add unit viewtypes and views to compiler/damlc/tests * Document reconstruction of HasInterfaceView * Move desugared types/values for interface views into DA.Internal.Desugar * Add desugarable function view w/ EViewInterface desugaring * Remove templateName and viewtype from generated EViewInterface * Update desugared-daml * Proof of concept: use _view -> EViewInterface prim via HasInterfaceView * Move view, HasInterfaceView to DA.Internal.Interface * Update desugared-daml tests * Stop removing and re-generating HasInterfaceView instances * Do not generate docs for generated "_view_" methods * Report errors with interface TypeConNames prettily * Fix InterfaceViewNotSpecified @ERROR to reflect new error text * Don't import magic `view` method from Prelude to avoid name clash * Update shake interface goto definition test locations * Temp disable view spec tests, will re-implement views in speedy * Add unit viewtype to Java code snippet docs * Update Interface syntax docs for views * Add unit viewtype to Transferrable.daml * Add back "empty" interface implementation to interfaces.rst * Re-enable view tests by having _view methods on InterfaceViews.daml file * Remove deprecated commented-out view desugaring code |
||
|---|---|---|
| .. | ||
| src | ||
| BUILD.bazel | ||
| README.md | ||
HTTP JSON Service
See "HTTP JSON API Service" on docs.daml.com for usage information.
Documentation can also be found in the RST format:
Development guidelines
The original endpoints for the JSON API followed some guidelines that should be kept in mind when considering extensions and changes to the API.
-
The JSON API is here to get basic ACS-using applications off the ground quickly, with a shallow development learning curve. It is not meant to support every ledger use case or every size of application. Always keep in mind that JSON API is an ordinary ledger client; there is nothing that it can do that any application written against the gRPC API could not do, and in a way that is more optimized for whatever advanced application someone might have in mind.
-
JSON API is not a REST API. That's one reason why REST isn't in the name, and that we never refer to it as REST anywhere in the documentation. It uses HTTP, and JSON, not REST. So "it's what REST does" is not considered at all in API design.
-
Instead, the most influential external design idea is that of minimizing the use of HTTP error codes, in favor of reporting status information in the response body, as linked from the JSON API documentation. So do not overthink HTTP status; we do report broadly reasonable status, but what matters is that the response error body is semantically useful. The sole exception is that, in most cases, gRPC errors upstream translate to the gRPC-recommended HTTP status codes; this is handled globally within json-api, so you do not have to think about this, as long as you do not suppress exceptions from the ledger client.
-
Endpoints should be POSTs, and input arguments should be supplied as a POST request body, not in the URL. This allows for obvious extension should more arguments be needed, whereas such extensions are tricky for URLs.
-
"Support the simplest, most common use cases" should always be favored heavily over "support anything someone might want to do with this endpoint".
-
As such, when considering how to present the arguments of an endpoint, don't include an argument simply because it is also present in a gRPC endpoint; consider whether it is actually important enough for the use cases described above.
-
Returning extra data is not free; it is a permanent cognitive burden on every new user of the endpoint. As such, if a piece of information will not be used by many users of the endpoint, it should probably be stripped away. Do not merely pass through everything that an associated gRPC endpoint happens to return.
-
It's preferable for a JSON API endpoint to add simplifying value. The best example of this is for template IDs; the JSON API lets you play fast-and-loose with package IDs because it helps you get off the ground quickly as described in (1), not because this should be done for all applications. A more complicated way that it adds value is with the query language. The easiest way to add simplifying value is to exclude rarely-needed arguments and results as mentioned in the above points.
-
The query language leans heavily on (1). It is meant to efficiently support a basic set of application queries, not be all things to all querying types. Supporting a broader set of query features means supporting that basic set worse in some ways, be it by obscuring the core feature set from newcomers or by penalizing performance of those core queries. As such, consider whether a query feature will be broadly useful for the types of applications listed in (1), among other things, before committing to supporting it.