Structured Content

Author: apidevrb

api-guidelines/api-design-principles/api-design-principles.md

@@ -0,0 +1,35 @@
+# Design Principles
+
+To compare the interface design approaches of SOAP-based web services to those of REST services, the former tend to be centered around operations that are usually use-case specific and reveal service implementation details (inside-out perspective). This leads to closely coupled systems which tend to get brittle and fragile as complexity grows. In contrast, REST is all about (business) entities found in the system and exposed as resource endpoints — leading to interfaces which abstract away implementation details (outside-in perspective) and are thereby more broadly usable and longer lasting. .
+
+## API Design Principles
+
+1. We prefer REST-based APIs
+2. We prefer systems to be truly RESTful
+3. We strive to build interoperating distributed systems that different teams can evolve in parallel
+
+An important principle for (RESTful) API design and usage is Postel's Law, aka [the
+Robustness Principle](http://en.wikipedia.org/wiki/Robustness_principle) (RFC 1122):
+
+> “Be liberal in what you accept, be conservative in what you send.” 
+
+The ability to extend service definitions after the initial release without affecting already deployed clients is key to preserve agility and evolvability of those services. For a more in-depth discussion regarding its applicability on API Design, please read the [Message Schema and Postel's Law](../message-schema/message-schema.md) chapter.
+
+Read the following to gain additional insight on the RESTful service architecture paradigm and general RESTful API design style:
+
+* Fielding Dissertation: [Architectural Styles and the Design of Network-Based Software
+  Architectures](http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)
+* Book: [REST in Practice: Hypermedia and Systems
+  Architecture](http://www.amazon.de/REST-Practice-Hypermedia-Systems-Architecture/dp/0596805829)
+* Book: [A Practical Approach to API Design](https://leanpub.com/restful-api-design)
+* Book: [Build APIs You Won't
+  Hate](https://leanpub.com/build-apis-you-wont-hate)
+* InfoQ eBook: [Web APIs: From Start to
+  Finish](http://www.infoq.com/minibooks/emag-web-api)
+* Lessons-learned blog: [Thoughts on RESTful API
+  Design](http://restful-api-design.readthedocs.org/en/latest/)
+
+We apply the RESTful web service principles to all kind of application components, whether they provide functionality via the Internet or via the intranet as larger application elements. We strive to build interoperating distributed systems that different teams can evolve in parallel.
+
+---
+This chapter was adopted from the [Zalando API Styleguide](https://github.com/zalando/restful-api-guidelines/blob/master/Introduction.md)

api-guidelines/api-design-process/api-design-process.md

@@ -0,0 +1,37 @@
+## API Modelling and Design Process
+
+The following API Modelling Process has been excerpted from chapter 4 and chapter 6 of [A Practical Approach to API Design](https://leanpub.com/restful-api-design) by D. Keith Casey Jr and James Higginbotham. (**This is just a brief summary for educational purpose - please consider buying the book to support their excellent work**)
+
+### API Modelling Process
+API modeling consists of 5 activities that help identify the requirements of your API design:1. Identify the participants, or actors, that will interact with your API2. Identify the activities that participants wish to achieve3. Separate the activities into steps that the participants will perform4. Create a list of API methods from the steps, grouped into common resource groups5. Validate the API by using scenarios to test the completeness of the APIThe goal of each step is to explore the requirements of the API from a variety of different perspectives: those involved (the participants), what they want to do (the activities), and how they will complete an activity (the steps). The modeling process will be iterative, so it should be expected that each modeling activity may require that you revisit the previous step as previously hidden details are exposed.
+### API Design Process
+As you move from the modeling to the design phase, you will be faced with a variety of decisions. Some of these will resolve easily, while others will take time and deliberation. Just know that it is difficult to get your API design right the first time. This is why we encourage you to spend time designing and prototyping your API before you start implementing it.
+
+#### Building Your Resource Taxonomy
+To get started building your taxonomy, make a list of the resources you have modeled already. These are often identified as the nouns in your system. Keep in mind that some resources may belong as a child collection of another resource.
+
+#### How to Handle Resource Relationships and Composition
+Resources often contain child resources or reference other resources. In these cases, the API design must ensure that one can interact with the top-level resource as well as nested and related resources.To better design our API, we need to understand the three types of resource relationships:
+ Relationship | Description--------------|-------------
+ Independent  | The resources exist stand alone without the other’s existence, but may reference each other        
+ Dependent    | One resource cannot exist without the existence of the parent resource
+ Associative  | The resources exist independently, however their relationship contains or requires additional properties to describe it
+How you design your API around related resources can be determined based on a few questions. The answers to these questions will determine if your resources are independent, dependent, or associative:
+1. Can both resources exist without the other? Then we have an ***Independent*** resource2. Does one resource exist only when the other exists? Then we have a ***Dependent*** resource3. Does the relationship between resources require more state than just the links between them? Then we have an ***Associative*** resource
+#### Defining Resource LifecyclesOnce we have identified our RESTful API resources, it is time to start mapping them to our HTTP verbs. During the API Modelling Process, we were able to capture most activities using a specific list of actions: “list”, “clear”, “view”, etc. Depending on the verbs you commonly use during modeling, you will likely find that certain ones can be mapped directly to REST patterns.#### Mapping Response Codes For Success and Failure
+Please see [HTTP Status Codes](../http-status-codes/http-status-codes.md) for a more in depth discussion.#### Expanding Resources Through Hypermedia LinkingAs you move from resource identification, it is time to explore the links (relationships) each resource will provide. Resource links are just like links within a web page - they describe the options available for navigation. Links may be used for a variety of reasons:
+1. To inform clients about the actions available given the resource’s current state2. Provide hints to actions that are authorized for the current user
+3. Allow clients to explore resource relationships
+
+The following is a quick summary of Hypermedia Linking
+
+* ***Link Thyself***: Every resource should define a link to itself. While this seems to be redundant, or perhaps wasteful, there is a valid reason for returning a link to a returned resource: clients should never have to track the link that returned a resource separate from the resource representation itself.
+* ***Resource State Linking***: Look for any constraints and state transitions that a resource may require. These constraints should be surfaced as links, offering insight into what actions are allowed and not allowed given the current state of a resource.
+* ***Relationship Linking***: Resources should include links to a parent resource, children, or related resources as identified during the previous taxonomy step.
+* ***Additional Navigation Links***: Most commonly used for collection responses, where you may need to offer pagination links for next and previous pages, and for navigation to other areas of the API.
+
+Please see [Hypermedia and Rest](../hypermedia-and-rest/hypermedia-and-rest.md) for a more in depth discussion of Hypermedia.
+
+---
+
+A good reference book for APIs and API Design is the afore mentioned [A Practical Approach to API Design](https://leanpub.com/restful-api-design) by D. Keith Casey Jr and James Higginbotham.

api-guidelines/api-design-review-process/api-design-review-process.md

@@ -0,0 +1,90 @@
+## API Design Review Process
+
+### Why
+We believe in APIs and in the API Economy. We are just at the beginning of our journey to an API driven company. There is no clear roadmap how to reach our goal. For sure it will be ways in which we stumble, sometimes fail but hopefully succeed in the end.
+
+There will be pros and cons how to handle and apply the style guide to real projects. There are many things to learn and to share with another. We have to keep improving the style guide, review process, and tools to capture our evolving knowledge and experience.
+
+To formalize the learning process we decided to establish the **API Design Review Process**. Each new or refactored API MUST be reviewed through this process.
+
+### Feedback
+We have now done a couple of API design reviews. Please give us feedback how we can improve this process!
+
+### Review process
+
+#### Who is responsible for scheduling the review?
+A representative of the project team that creates the service MUST contact the CTO office. In most cases the representative is the API designer/architect.
+
+#### How to plan the review?
+It is the responsibility of the team to plan their resources for the API review and to talk with the team leaders of CTO office to organize reviewers. Together they decide on the appropriate time box for the review.
+
+#### Tooling
+Currently we use a **private GitHub repo** for each API review.
+The `README.md` should contain the following informations:
+
+- Purpose of the API
+- Links to the API description
+- Start date of the review
+- End date of the review
+- Mandatory reviewers including state
+- State of the review itself
+- Conclusion
+
+#### API description
+It is necessary to provide a formal description of the API to review it.
+The API designer has to provide a Swagger description (prefered) or an equivalent description. Providing a running system or a mock to work with the API is highly appreciated.
+
+#### Reviewing the API
+It is up to the API designer and reviewer how to perform the review. It is a good idea to schedule a meeting and step through the API and talk with the reviewers about the functionality and intention. That's a good way to cut down review times because questions and missunderstandings can be solved immediately. Others prefer to review the API without a formal meeting.
+
+Changes requests are stored as issues in the GitHub repo.
+Each reviewer has to update his personal review state in GitHub.
+
+#### Mandatory vs optional reviewers
+During the review planning at least two reviewers will be fixed.
+The mandatory reviewers are explicitly named in the GitHub review repo.
+
+Each review is open for feedback from a wide group of other people.
+That includes all interested architects, team members, and clients that will use the API. The CTO office informs - per default - all architects on pending reviews. The team is free to add optional reviewers of its own.
+
+#### How issues should be raised and addressed
+We use the GitHub issue mechanism for a transparent communication during the review. Each issue must be categorized as follows:
+
+- Must change: Must be changed in the API design and implementation
+- Improvement: Should be changed. Depends on the team
+- Question: For Questions/Discussions and clarifications
+
+Please use Github labels for the classification.
+
+#### Time boxed reviews
+The review is time boxed. It starts at a given date and - more importantly - it ends at a predefined date. The outcome of the review is documented in the GitHub repo `README.md`.
+
+#### When is an API reviewed and can be implemented?
+After finishing the API review there will be some change requests for the API.
+Most of them might be easy to fix/change and the API designer should do that immediately during and after the review. Other changes may need more effort and planning how to address them.   
+
+The next steps and the the conclusion how to proceed with the change requests is written down in the **conclusion** section of the GitHub repo `README.md`.
+The implementation can start after finishig the review.
+
+#### Learnings from the review and feedback to the style guide
+After each review the API designer/team should provide a feedback issue in the
+API style guide project and mark it with the label **feedback**.
+The feedback has to cover at least the topics
+
+- How helpful was the API style guide for your design process?
+	- Which sections especially?
+	- What did you learn for future API designs?
+- How to improve the style guide itself?
+	- Which information do you miss?
+	- Which guideline do you not agree with?
+- How to improve the API review process itself?
+	- What can we improve regarding tooling, planning etc.
+
+#### How to measure success for the API review
+There are two goals in an API review
+
+##### Improve the API itself
+It's not that easy to measure the improvement of the API. It is best to look at it from a client perspective. How costly (in time and effort) is the programming against the API for a developer? Can you quantify it and imporve on the KPI?
+
+##### Learn to design APIs
+This is even harder to measure than the one above. If you can think of a good way to measure our ability to continously improve our API Deisgn skills and processes, we would love to hear it.