Skip to content

Commit 6b3b33c

Browse files
tovrleaftovrleaf
committed
Release 3.0.0
1 parent ab06ceb commit 6b3b33c

14 files changed

Lines changed: 877 additions & 25 deletions

‎CHANGELOG.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,28 @@ All approved changes to Development Guidelines will be documented in this file.
44

55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this log versions changes with date in `YYYY-MM-DD` format.
66

7+
## 2024-11-05 [v3.0.0]
8+
### Added
9+
#### Mobile Guidelines
10+
- Codebase → Version Control → SHOULD use fast-forward merges only from feature branch to main branch
11+
- Codebase → Version Control → SHOULD implement bug fixes to feature branch and cherry picked them to main and potential release branch
12+
- Codebase → Version Control → RECOMMENDED to squash feature branches before merging to main branch
13+
- Codebase → Version Control → MUST preserve release tags forever
14+
- Release Management → MUST use semantic versioning for releases (tags)
15+
- Environments → Data → SHOULD preserve all release artefacts forever
16+
### Changed
17+
#### Development Guidelines
18+
- Codebase → Version Control`[- → Branching-]` → MUST fork feature (and release) branches from main branch
19+
- Codebase → Version Control`[- → Branching-]` → SHOULD protect default branch from pushes
20+
### Removed
21+
#### Development Guidelines
22+
- Codebase → Version Control → Branching → Mobile Development → SHOULD use fast-forward merges only from feature branch to main branch
23+
- Codebase → Version Control → Branching → Mobile Development → SHOULD implement bug fixes to feature branch and cherry picked them to main and potential release branch
24+
- Codebase → Version Control → Branching → Mobile Development → RECOMMENDED to squash feature branches before merging to main branch
25+
- Codebase → Version Control → Branching → Mobile Development → MUST preserve release tags forever
26+
- Release Management → Mobile Development → MUST use semantic versioning for releases (tags)
27+
- Environments → Data → Mobile Development → SHOULD preserve all release artefacts forever
28+
729
## 2024-06-05 [v2.4.0]
830
### Added
931
#### Development Guidelines

‎releases/SOK-AGv3.0.0.html‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
<!DOCTYPE html>
2+
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="generator" content="pandoc" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
7+
<meta name="author" content="Development Community" />
8+
<meta name="keywords" content="api, guidelines" />
9+
<title>SOK API Guidelines</title>
10+
<style>
11+
html {
12+
line-height: 1.5;
13+
font-family: Georgia, serif;
14+
font-size: 20px;
15+
color: #1a1a1a;
16+
background-color: #fdfdfd;
17+
}
18+
body {
19+
margin: 0 auto;
20+
max-width: 36em;
21+
padding-left: 50px;
22+
padding-right: 50px;
23+
padding-top: 50px;
24+
padding-bottom: 50px;
25+
hyphens: auto;
26+
overflow-wrap: break-word;
27+
text-rendering: optimizeLegibility;
28+
font-kerning: normal;
29+
}
30+
@media (max-width: 600px) {
31+
body {
32+
font-size: 0.9em;
33+
padding: 1em;
34+
}
35+
h1 {
36+
font-size: 1.8em;
37+
}
38+
}
39+
@media print {
40+
body {
41+
background-color: transparent;
42+
color: black;
43+
font-size: 12pt;
44+
}
45+
p, h2, h3 {
46+
orphans: 3;
47+
widows: 3;
48+
}
49+
h2, h3, h4 {
50+
page-break-after: avoid;
51+
}
52+
}
53+
p {
54+
margin: 1em 0;
55+
}
56+
a {
57+
color: #1a1a1a;
58+
}
59+
a:visited {
60+
color: #1a1a1a;
61+
}
62+
img {
63+
max-width: 100%;
64+
}
65+
h1, h2, h3, h4, h5, h6 {
66+
margin-top: 1.4em;
67+
}
68+
h5, h6 {
69+
font-size: 1em;
70+
font-style: italic;
71+
}
72+
h6 {
73+
font-weight: normal;
74+
}
75+
ol, ul {
76+
padding-left: 1.7em;
77+
margin-top: 1em;
78+
}
79+
li > ol, li > ul {
80+
margin-top: 0;
81+
}
82+
blockquote {
83+
margin: 1em 0 1em 1.7em;
84+
padding-left: 1em;
85+
border-left: 2px solid #e6e6e6;
86+
color: #606060;
87+
}
88+
div.abstract {
89+
margin: 2em 2em 2em 2em;
90+
text-align: left;
91+
font-size: 85%;
92+
}
93+
div.abstract-title {
94+
font-weight: bold;
95+
text-align: center;
96+
padding: 0;
97+
margin-bottom: 0.5em;
98+
}
99+
code {
100+
font-family: Menlo, Monaco, 'Lucida Console', Consolas, monospace;
101+
font-size: 85%;
102+
margin: 0;
103+
}
104+
pre {
105+
margin: 1em 0;
106+
overflow: auto;
107+
}
108+
pre code {
109+
padding: 0;
110+
overflow: visible;
111+
overflow-wrap: normal;
112+
}
113+
.sourceCode {
114+
background-color: transparent;
115+
overflow: visible;
116+
}
117+
hr {
118+
background-color: #1a1a1a;
119+
border: none;
120+
height: 1px;
121+
margin: 1em 0;
122+
}
123+
table {
124+
margin: 1em 0;
125+
border-collapse: collapse;
126+
width: 100%;
127+
overflow-x: auto;
128+
display: block;
129+
font-variant-numeric: lining-nums tabular-nums;
130+
}
131+
table caption {
132+
margin-bottom: 0.75em;
133+
}
134+
tbody {
135+
margin-top: 0.5em;
136+
border-top: 1px solid #1a1a1a;
137+
border-bottom: 1px solid #1a1a1a;
138+
}
139+
th {
140+
border-top: 1px solid #1a1a1a;
141+
padding: 0.25em 0.5em 0.25em 0.5em;
142+
}
143+
td {
144+
padding: 0.125em 0.5em 0.25em 0.5em;
145+
}
146+
header {
147+
margin-bottom: 4em;
148+
text-align: center;
149+
}
150+
#TOC li {
151+
list-style: none;
152+
}
153+
#TOC ul {
154+
padding-left: 1.3em;
155+
}
156+
#TOC > ul {
157+
padding-left: 0;
158+
}
159+
#TOC a:not(:hover) {
160+
text-decoration: none;
161+
}
162+
code{white-space: pre-wrap;}
163+
span.smallcaps{font-variant: small-caps;}
164+
span.underline{text-decoration: underline;}
165+
div.column{display: inline-block; vertical-align: top; width: 50%;}
166+
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
167+
ul.task-list{list-style: none;}
168+
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
169+
</style>
170+
171+
172+
<!--[if lt IE 9]>
173+
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
174+
<![endif]-->
175+
</head>
176+
<body>
177+
<header id="title-block-header">
178+
<h1 class="title">SOK API Guidelines</h1>
179+
<p class="subtitle"><p><em>A handbook created by developers for
180+
developers to help engineering teams align their software practices and
181+
share know-how.</em></p></p>
182+
<p class="author">Development Community</p>
183+
<p class="date">2024-11-05<br />v3.0.0</p>
184+
<div class="abstract">
185+
<div class="abstract-title">Abstract</div>
186+
<p>APIs are the new normal when it comes to modern software architecture
187+
since they enable decoupling and easy communication between services.
188+
APIs are easy to own, deploy and operate by our teams, so we want to
189+
help our engineers with some guidelines to help them design, implement
190+
and maintain their APIs.</p>
191+
<p>Our APIs enable us to build platforms that support our business
192+
needs. API First approach should be adopted in order to support those
193+
needs in a clear and structured way. API definition starts outside the
194+
code and ideally involves all actors that are relevant to the domain.
195+
API First encompasses a set of quality-related standards and fosters a
196+
peer review culture including a lightweight review procedure. We
197+
encourage our teams to follow them to ensure that our APIs:</p>
198+
<ul>
199+
<li>are easy to understand and learn</li>
200+
<li>are general and abstracted from specific implementation and use
201+
cases</li>
202+
<li>are robust and easy to use</li>
203+
<li>have a common look and feel</li>
204+
<li>are consistent with other teams’ APIs and our global
205+
architecture</li>
206+
</ul>
207+
</div>
208+
</header>
209+
<nav id="TOC" role="doc-toc">
210+
211+
</nav>
212+
<p style="text-align:center">
213+
<img src="../assets/S-Logo.png" style="clear:both" />
214+
</p>
215+
<p>APIs are the new normal when it comes to modern software architecture
216+
since they enable decoupling and easy communication between services.
217+
APIs are easy to own, deploy and operate by our teams, so we want to
218+
help our engineers with some guidelines to help them design, implement
219+
and maintain their APIs.</p>
220+
<blockquote>
221+
<p>The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”,
222+
“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this
223+
document are to be interpreted as described in <a
224+
href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p>
225+
</blockquote>
226+
<h1 data-number="1" id="principles"><span
227+
class="header-section-number">1</span> Principles</h1>
228+
<ul>
229+
<li>RECOMMENDED to read <a
230+
href="https://opensource.zalando.com/restful-api-guidelines/">Zalando
231+
RESTful API and Event Guidelines</a> as a base and use as a
232+
reference</li>
233+
<li>SHOULD implement versioning</li>
234+
<li>MUST have versioning strategy decided prior the first release</li>
235+
<li>RECOMMENDED not use URL versioning</li>
236+
<li>RECOMMENDED to use HTTP Headers to carry version information</li>
237+
<li>RECOMMENDED have version information also in response headers</li>
238+
<li>MUST not break backward compatibility once the version has been
239+
released</li>
240+
</ul>
241+
<h1 data-number="2" id="appendix-1"><span
242+
class="header-section-number">2</span> Appendix 1</h1>
243+
<h2 data-number="2.1" id="commentary"><span
244+
class="header-section-number">2.1</span> Commentary</h2>
245+
<h3 data-number="2.1.1" id="resource"><span
246+
class="header-section-number">2.1.1</span> Resource</h3>
247+
<p>A resource is a conceptual mapping to a set of entities, not the
248+
entity that corresponds to the mapping at any particular point in time.
249+
In other word, resource is unique and anything with an URL and entity is
250+
its representation of that resource in current time when requested.</p>
251+
<p>Even though we’re recommending to adapt some of <a
252+
href="https://opensource.zalando.com/restful-api-guidelines/">Zalando’s
253+
good practices</a>, we’re not saying your APIs should be RESTful (but
254+
they can be!) or just <a
255+
href="https://kieranpotts.com/rebranding-rest/">APIs built with good old
256+
conventions with HTTP semantics on distributed World Wide Web</a>.</p>
257+
</body>
258+
</html>

‎releases/SOK-AGv3.0.0.pdf‎

185 KB
Binary file not shown.

0 commit comments

Comments
 (0)