haufe-lexware / api-style-guide Goto Github PK

Related to #26

General intro (primarily for public apis)
http://nordicapis.com/api-discovery-11-ways-to-find-apis/

Current approaches to API discovery:
https://github.com/zalando-incubator/api-discovery
https://github.com/apis-json/api-json
https://developers.google.com/discovery/v1/reference/

Service Documents for Discovery
https://bitworking.org/projects/atom/draft-ietf-atompub-protocol-14.html
https://github.com/hypoport/hal-service-document-consumer
See also comment train in #26 for more

hlgr360 5:28 PM
@salvador.juan: Is this a problem of code before api? Is this another instance of a tool/framework making assumptions rather than us Engineers designing the right API and then implementing it?

when picking up the code, and generating the documentation
this makes me wonder .. because I would thought that we should do first the right API .. and then do the code. convinience frameworks are more often than not evil in that regard
by thinking that we can get easy lunch on the inside, we screw up the one public interface we should really care about the api is long living .. code is forever changing
I suggest you look for the reverse path in frameworks
you have a swagger ... lets generate code from it
that is API first .. the other one is (potentially) repeating the same mistake which doomed SOA ... take a code signature and turn it into a network accessible interface
this led to close coupling and the horrors of ESB hell
convinience is a nice to have .. but it should not warp what our priority should be .. to have the right API ... code follows
swagger provides tooling to create code from swagger
just ad-hoc .... have you looked at https://github.com/swagger-api/swagger-codegen

github.com
swagger-api/swagger-codegen
swagger-codegen contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration.
here is a blog post from Kin Lane: http://apievangelist.com/2015/06/06/comparison-of-automatic-api-code-generation-tools-for-swagger
apievangelist.com
Comparison of Automatic API Code Generation Tools For Swagger
where he compares some tooling

Pubslih/ subscribe pattern and callbacks via web hooks

Since I have seen a few attempts to rebrand SOA style architectures (functional decomposition) as Microservices with REST

to me a microservice represents a domain ... and that domain is seperated from another domain through some constrains ... it could be process (the concept of microflow from the BPEL days) .. or time (changes in one domain are decoupeld from changes in another along time) .. or or ..
it is hard to describe it because I feel that if you look a the context it just pops out to me .. ... for instance SAP is a single domain for me, even though it has plenty of systems inside
I invest time and resources to decouple domains from each other .. this is where an REST API comes into play. A REST API is not cheap .. it costs (design) time and - in most cases - should allow self service (another aspect of decoupling and obtaining more speed) through API management
within a domain there could be multiple services
each interacting with the other .. most of the time I would not use REST between those, but more an IPC style framework like gprot, thrift, protobuf etc ...

I don;t know what I try to get to with this post except maybe spark a discussion and thinking on the granularity of a micro service

it could be a single docker container .. but it could also be 10's of containers

Design process is excerpted from A Practical Approach to API Design by D. Keith Casey Jr and James Higginbotham. Obtain permission from author that this is ok with them

Tora posted some good information on using RestEASY in her blog entry at http://dev.haufe-lexware.com/generate-swagger/

within Aka-I we discussed valid and invalid url patterns regarding collection resources and query parameters, we decided this way p.e. collection for users

• to retrieve a list both urls, with and without trailing slash is valid: /users and /users/
• to retrieve a list filtered with further query params, only the variant /users?offset= is valid, not the variant with the combination "/?" /users/?offset= in it, because the "?" gets interpreted as a further (id) value.

http://www.kennethlange.com/posts/7_tips_for_designing_a_better_rest_api.html

It violates the notion of outside-in design. Section 5 in above link

In many existing web applications we have to deal with mutliple Ids (Composite Keys). Let's say, Order 4711 and Order LIne 42, whereas the Order Lines are exposed via the rest API.

How do we apply this to the REST URL structure?

1) odernlines/4711/42 
   or
2) odernlines(4711,42)

Are there any guidelines?

http://amundsen.com/examples/fielding-props/

The ability to add, delete, modify, or read properties of resources

We have now done a couple of API design reviews. We need to do a retro and come with an initial written down API design review process we ask teams to adhere to. This can include (but is not limited to):

• overall review process
• mandatory vs optional reviewers
• how issues should be raised and addressed
• clearly time boxing reviews
• provide motivation and 'how do you define and measure success' for API
• how can learnings from the review flow back to the style guide
• when is an API reviewed and can be implemented

https://stripe.com/blog/idempotency

Great message thread on rocket:

ou CAN design extensible schemas even in XML Schema ... but it means you need to be extremely mindfull about it
i.e. you need to make both the attribute space and child elements extensible ... xsd:any is your friend .. but it is very tedious
most tooling interprets schema literally, not extensibly
so you DO need documentation and you might even choose to use Schemas
but how you design the Schema and how you end up using the Schema (for documentation vs for code generation) - that will make or break your extensibility and robustness
you could document your events RFC style .. and this is how the internet was build
you do not need schema
problem is that the step from schema as documentation to schema as input to code generation is tantalizing small and it takes a lot of will power and awareness to decide to not do it
that is all I am saying .. we are humans afterall

Caballero, Mallku @CaballeroM 9:29 AM
All I meant to say is that a non-enforced schema can be a good tool for documentation
👍 1

Reinhardt, Holger @reinhardth 9:29 AM
to which I wholeheartedly agree .. 100% ... +1
question is .. who do you document it for
humans?
probably
then how does Avro come into play
Humans do not need Avro ... machines, code, tooling needs avro 🙂

so it looks like we do not have a disagreement after all 🙂
non-enforced schemas are a great way to document ... so is RFC style
for as long as everyone know it should not be used for blindly auto-generating client code .. and/or if you do that ... a lot more attention has to be paid to make the schema extensible
maybe even enforced by have a lint which alerts you if non-extensible schema is being check-in or used
so you either protect yourself against human fallacies by using a format whcih can not be readily used for code generation or by tooling which enforces extensibility
the way to hell is paved with good intention .. and it is upon us to make sure we account for human fallacies
there will be developers other than those participating in this discussion writing code .. it is those folks in 6 months I worry about, not about you or anyone on this message thread

Caballero, Mallku @CaballeroM 9:35 AM
+1

From a conversation on Rocket

The only place for GraphQL in my rule ebook is between the backend and the mobile app .. the mobile app api. Tthat api is mobile app specific .. and it makes sense to leverage the whole power of the React/Redux stack in that case BUT that is not the same API as for instance a partner API or a public API or an integration API

Currently the API style guide reads as a cross between education and wish list. But our intent is that this style guide provides the default preference for our API design and development process. And this means making choices.
We should add a preamble stating that Haufe.Group teams can deviate from the style guide if they provide the arguments justifying it.

I was thinking about the problem described above some more over the weekend. ... the notion that in order to truely do hypermedia you would need to first access the service document of the API (to stay in the terminology of Atom PUB protocol), find the resource _link based on the relationship attribute value, and only then can pull the resource
I send that question to mike Ammundsen and Irakli .. two experts on this from one of my past lifes

will forward their answer (when they respond)

but my engineering self is thinking that you can assume to know the list of relation attributes values a priori .. the list of rel attr values present the semantic dictionary (rel val = resource plus operation) .. and the meaning of each value is fixed and can not be changed in a non-breaking manner

a value of 'user' must always mean an 'user' over the lifetime of the api .. you can add new attr values .. you can add new fields to existing attr values .. but you can't change the meaning of an existing one
so here is the basic idea of a service document (as Atom Pub defined it .. to me still one of the gold standards of XML based API's ..)

http://www.greenbytes.de/tech/webdav/rfc5023.html#rfc.section.8.3.1

The purpose of the service document such that a client has a single place to start 'discovering' the API without having to hard code the exact structure in the client (and thereby creating close syntactical coupling)

I think a most basic solution to deal with the potential costs of 'alwasy having to do 2 calls' is to retrieve the service document only once and cache it on the client side ..

the caching could be expiring based on duration or through a caching header indicating the current version of the service document .. if the version from the server is different from the client .. the client 'rediscovers' the service document and prepares something like a lookup table for resources
so you have an effective cost of one additional transaction at the first time the client connects .. and then only if the service document changes
in between those discovery steps the API interactions flow pretty much the same as if you had a-priori knowledge of the API .. you need a resource, you do a lookup in the hash table for the link (discovered through the service document interaction) you do the call
so based on this .. here are some links I found

https://github.com/hypoport/hal-service-document-consumer
hal-service-document-consumer - A library to consume HAL based service documents of restful services.

on HAL and swagger
http://stackoverflow.com/questions/24389733/document-hal-links-from-spring-hateoas-with-swagger
Document HAL "_links" from Spring Hateoas (with swagger)?

From a convo on mantis-api channel:

• I am curious what others think .. so yes, chattiness is a concern .. and this is one of the primary drivers behind graphQL
  http://www.freshblurbs.com/blog/2015/06/25/api-representations-prefer.html
  Creating Client-Optimized Resource Representations in APIs

One of the most important design principles for an API program is to embrace that APIs are products. It follows that successful APIs, much like products, must provide user-optimized experiences. Case in point: it is clearly inappropriate to send a mobile application large response payloads. Your API may get away with it when responding to a request from an enterprise system communicating over a high-speed fiber-optic connection. Some clients may even want to get a rich response, but in general assuming that network is reliable and/or bandwidth is infinite is a fallacy, on the web.

• especially read the comment section
  http://spec.transclude.io
  spec.transclude.io
  Transclude Preference for the HTTP Prefer Header
  The specification for Transclude preference is an extension to the Prefer Header for HTTP
  is referred there

Transclude preference notifies the server that the client would prefer the server to proactively transclude certain content represented by links of indicated link relation types. The notion of "link relation type", in this context is as defined by [RFC5988].
I really like that concept .. and it provides some means of the client controlling the scope of the resource representation .. which i think your main question was

http://nordicapis.com/day-in-the-life-of-an-api-developer-evangelist/
http://blogs.ca.com/2015/07/28/why-your-company-needs-an-api-evangelist/

As of now, the section on error handling references both the vnd.error draft and RFC 7807.

At some point (proposal: in 6 months from now, i.e. November 2017), we should re-evaluate whether it makes more sense to settle for one of the formats. One of our tenets is that familiar formats make it easier for developers to use an API - if we stick with one format for future APIs, then chances are better that developers know it already.

Not sure if this is covered - as a reminder for me to make naming and style conventions explicit.

It is not being followed for over a year now. A mandatory rule being systematically ignored without consequences is worse than having no rule at all. Asking for comments.

Currently, the versioning of APIs is described under "URI components", which may not be prominent enough. Links between the following topics can be improved:

• Evolvable API design (don't versionize)
• Versioning (in case you screwed up and/or did a complete redesign)
• Hypermedia elements (which can also help creating evolvable APIs)

Inspired by discussions around the office and this https://medium.com/netflix-techblog/netflix-oss-batch-requests-with-ruby-on-rails-and-ember-js-4dfdd4b351da

From an email convo:

Die _link Elemente erlaube eine starke semantische Entkopplung des Clients vom Backend.

Das Prinzip ist relativ einfach .. anstelle das Wissen über die konkrete URL Struktur der API in den Client hart zu verdrahten, kennt der Client nur die Relationship Attribute Values. Um eine bestimmte Operation mit einem bestimmten Relationship Attribute Value durchzuführen, findet der Client das matching _link Element und benutzt die darin embedded URL ‘as-is’ (mit der Exception fuer den Backend Server bei Injektion des ‘Forwarded’ Header durch den vorgeschalteten APi Management Proxy)

Das erlaubt eine spätere Änderung der URL Struktur der API, ohne dass der Clients verändert werden muss. Das bedingt natürlich auch, dass Ihr die _link Elemente nicht einfach ignoriert, sondern sie entsprechend der Spezifikation nutzt. Eine Google Search zeigt eine ziemlich grosse Anzahl von client libs, die ihr entsprechend fuer Eure Anwendung evaluieren könnt.

API Lifecycle is larger than just the design:

• design (design, review)
• implementation (frameworks)
• regression testing and QA (tooling, approaches)
• production (API management, tooling, monitoring)
• versioning (extending vs versioning)
• depreciating (communication)

https://people.mpi-inf.mpg.de/~jblanche/api-design.pdf