| <!doctype html> |
| <!-- |
| Minimal Mistakes Jekyll Theme 4.4.1 by Michael Rose |
| Copyright 2017 Michael Rose - mademistakes.com | @mmistakes |
| Free for personal and commercial use under the MIT license |
| https://github.com/mmistakes/minimal-mistakes/blob/master/LICENSE.txt |
| --> |
| <html lang="en" class="no-js"> |
| <head> |
| <meta charset="utf-8"> |
| |
| <!-- begin SEO --> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <title>API Constraints - Apache ServiceComb</title> |
| |
| |
| |
| |
| <meta name="description" content="API Constraints"> |
| |
| |
| |
| |
| <meta name="author" content=""> |
| |
| <meta property="og:locale" content="en"> |
| <meta property="og:site_name" content="Apache ServiceComb"> |
| <meta property="og:title" content="API Constraints"> |
| |
| |
| <link rel="canonical" href="https://github.com/pages/apache/incubator-servicecomb-website/docs/users/service-interface-constraints/"> |
| <meta property="og:url" content="https://github.com/pages/apache/incubator-servicecomb-website/docs/users/service-interface-constraints/"> |
| |
| |
| |
| <meta property="og:description" content="API Constraints"> |
| |
| |
| |
| <meta name="twitter:site" content="@ServiceComb"> |
| <meta name="twitter:title" content="API Constraints"> |
| <meta name="twitter:description" content="API Constraints"> |
| <meta name="twitter:url" content=""> |
| |
| |
| <meta name="twitter:card" content="summary"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <script type="application/ld+json"> |
| { |
| "@context" : "http://schema.org", |
| "@type" : "Person", |
| "name" : "Apache ServiceComb", |
| "url" : "https://github.com/pages/apache/incubator-servicecomb-website", |
| "sameAs" : null |
| } |
| </script> |
| |
| |
| |
| <meta name="google-site-verification" content="HvJjNd7vvJ-yjSTHlBiIWEYxp_Hrz-PYEY5Idz9LRcA" /> |
| |
| |
| |
| |
| <!-- end SEO --> |
| |
| |
| <link href="/feed.xml" type="application/atom+xml" rel="alternate" title="Apache ServiceComb Feed"> |
| |
| <!-- http://t.co/dKP3o1e --> |
| <meta name="HandheldFriendly" content="True"> |
| <meta name="MobileOptimized" content="320"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <script> |
| document.documentElement.className = document.documentElement.className.replace(/\bno-js\b/g, '') + ' js '; |
| </script> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/1.7.1/clipboard.min.js"></script> |
| <script src="/assets/vendor/prism/prism.js"></script> |
| |
| <script type="text/javascript" async |
| src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML"> |
| </script> |
| |
| <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/css/bootstrap.min.css" integrity="sha384-/Y6pD6FV/Vv2HJnA6t+vslU6fwYXjCFtcEpHbNJ0lyAFsXTsjBbfaDjzALeQsN6M" crossorigin="anonymous"> |
| |
| <script src="https://www.apachecon.com/event-images/snippet.js"></script> |
| <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.11.0/umd/popper.min.js" integrity="sha384-b/U6ypiBEHpOf/4+1nzFpr53nxSS+GLCkfwBdFNTxtclqqenISfwAzpKaMNFNmj4" crossorigin="anonymous"></script> |
| <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/js/bootstrap.min.js" integrity="sha384-h0AbiXch4ZDo7tp9hKZ4TsHbi047NrKGLO3SEJAg45jXxnGIfYzk4Si90RDIqNm1" crossorigin="anonymous"></script> |
| <!-- For all browsers --> |
| <link rel="stylesheet" href="/assets/css/main.css"> |
| <link rel="stylesheet" href="/assets/vendor/prism/prism.css"> |
| |
| <!--[if lte IE 9]> |
| <style> |
| /* old IE unsupported flexbox fixes */ |
| .greedy-nav .site-title { |
| padding-right: 3em; |
| } |
| .greedy-nav button { |
| position: absolute; |
| top: 0; |
| right: 0; |
| height: 100%; |
| } |
| </style> |
| <![endif]--> |
| |
| <meta http-equiv="cleartype" content="on"> |
| |
| <!-- start custom head snippets --> |
| |
| <!-- insert favicons. use http://realfavicongenerator.net/ --> |
| <link href="https://fonts.loli.net/css?family=Roboto:400,500,700|Source+Code+Pro" rel="stylesheet"> |
| <script src="/assets/js/custom.js"></script> |
| <!-- end custom head snippets --> |
| |
| </head> |
| |
| <body class="layout--single"> |
| |
| <!--[if lt IE 9]> |
| <div class="notice--danger align-center" style="margin: 0;">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> to improve your experience.</div> |
| <![endif]--> |
| <div class="masthead" onmouseleave="$('#childrenShow').css('display', 'none')"> |
| <div class="masthead__inner-wrap"> |
| <div class="masthead__menu"> |
| <nav id="site-nav" class="greedy-nav"> |
| |
| <a class="site-title active" href="/"><img src="https://www.apache.org/img/servicecomb.png"></a> |
| |
| <ul class="visible-links"> |
| |
| |
| |
| |
| |
| <li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')"> |
| |
| <a href="/">Home</a> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| <li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')"> |
| |
| <a href="/developers/">Projects</a> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| <li class="def-nav-li" onmouseenter="$('#childrenShow').css('display', 'block')"> |
| |
| |
| |
| |
| |
| <a class="active" href="/docs/users/">Documentation</a> |
| |
| |
| <ul id="childrenShow" class="def-children-show-en" onmouseleave="$('#childrenShow').css('display', 'none')"> |
| |
| <li><a href="/docs/getting-started/" class="">Getting started</a></li> |
| |
| <li><a href="/docs/users/" class="">Docs</a></li> |
| |
| <li><a href="/slides/" class="">Video</a></li> |
| |
| <li><a href="/faqs/" class="">FAQ</a></li> |
| |
| </ul> |
| </li> |
| |
| |
| |
| |
| |
| |
| <li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')"> |
| |
| <a href="/year-archive/">Blogs</a> |
| |
| </li> |
| |
| |
| |
| |
| |
| |
| <li class="masthead__menu-item" onmouseenter="$('#childrenShow').css('display', 'none')"> |
| |
| <a href="/release/">Downloads</a> |
| |
| </li> |
| |
| |
| </ul> |
| <button><div class="navicon"></div></button> |
| <ul class="hidden-links hidden"></ul> |
| <div class="nav-lang"> |
| |
| |
| <a href=/cn/docs/users/service-interface-constraints/>ä¸æ–‡</a> |
| |
| </div> |
| </nav> |
| </div> |
| </div> |
| </div> |
| |
| |
| |
| |
| |
| |
| <div id="main" role="main"> |
| |
| <div class="sidebar sticky"> |
| |
| <div class="back-to-home"><a href="/">Home</a> > API Constraints</div> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <nav class="nav__list"> |
| |
| <input id="ac-toc" name="accordion-toc" type="checkbox" /> |
| <label for="ac-toc">Toggle Menu</label> |
| <ul class="nav__items"> |
| |
| <li> |
| |
| <span class="nav__sub-title">Java Chassis User Guide</span> |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="/references/java-chassis/zh_CN/index.html" class="">Java Chassis 3</a></li> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="/references/java-chassis/2.x/zh_CN/index.html" class="">Java Chassis 2</a></li> |
| |
| </ul> |
| |
| </li> |
| |
| <li> |
| |
| <span class="nav__sub-title">Pack User Guide</span> |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="https://github.com/apache/servicecomb-pack/blob/master/docs/user_guide.md" class="">0.5.0</a></li> |
| |
| </ul> |
| |
| </li> |
| |
| <li> |
| |
| <span class="nav__sub-title">ServiceCenter User Guide</span> |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="https://service-center.readthedocs.io/en/latest/user-guides.html" class="">2.0.0</a></li> |
| |
| </ul> |
| |
| </li> |
| |
| <li> |
| |
| <span class="nav__sub-title">Kie User Guide</span> |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="https://kie.readthedocs.io/en/latest/" class="">0.2.0</a></li> |
| |
| </ul> |
| |
| </li> |
| |
| <li> |
| |
| <span class="nav__sub-title">Mesher User Guide</span> |
| |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| <li><a href="https://mesher.readthedocs.io/en/latest/" class="">1.6.3</a></li> |
| |
| </ul> |
| |
| </li> |
| |
| </ul> |
| </nav> |
| |
| |
| |
| </div> |
| |
| |
| |
| <article class="page" itemscope itemtype="http://schema.org/CreativeWork"> |
| <meta itemprop="headline" content="API Constraints"> |
| <meta itemprop="description" content="API Constraints"> |
| |
| <meta itemprop="dateModified" content="August 15, 2017"> |
| |
| <div class="page__inner-wrap"> |
| |
| |
| <header> |
| <h1 class="page__title" itemprop="headline">API Constraints |
| </h1> |
| |
| </header> |
| |
| |
| |
| <section class="page__content" itemprop="text"> |
| <aside class="sidebar__right"> |
| <nav class="toc"> |
| <!-- <header><h4 class="nav__title"><i class="fa fa-file-text"></i> On This Page</h4></header> --> |
| <ul class="toc__menu" id="markdown-toc"> |
| <li><a href="#api-constraints" id="markdown-toc-api-constraints">API Constraints</a></li> |
| <li><a href="#detailed-constraint-list" id="markdown-toc-detailed-constraint-list">Detailed Constraint List</a></li> |
| <li><a href="#protocol-difference" id="markdown-toc-protocol-difference">Protocol Difference</a></li> |
| </ul> |
| |
| </nav> |
| </aside> |
| |
| <h2 id="api-constraints">API Constraints</h2> |
| <p>A Java Chassis API constraints is that an API definition should describe its usage. You can identify how to call the API without checking the code.</p> |
| |
| <p>As developers, we aim at making our APIs easy to be called. However, developers have different understanding about this aim.</p> |
| |
| <p>For example:</p> |
| |
| <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">public</span> <span class="nc">Person</span> <span class="nf">query</span><span class="o">(</span><span class="nc">String</span> <span class="n">id</span><span class="o">);</span> |
| <span class="kd">public</span> <span class="nc">Object</span> <span class="nf">query</span><span class="o">(</span><span class="nc">String</span> <span class="n">id</span><span class="o">);</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">Person</span> <span class="o">{</span><span class="nc">String</span> <span class="n">name</span><span class="o">;}</span> |
| </code></pre></div></div> |
| |
| <p>Obviously, if API 1 is called, we know that an ID parameter of String type needs to be transferred. The returned value is of Person type, which contains a string-typed name parameter. If API 2 is called, we do not know how to process the returned value, and need to refer to documents provided by the service provider. API 2 is developed in the perspective of RPC developers.</p> |
| |
| <p>To release an API as a REST API, we can use the swagger file; specify the ID to be transmitted using RequestParam, PathVariable, or RequestBody; or use the label provided by SpringMVC or JAX-RS.</p> |
| |
| <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">public</span> <span class="nc">Person</span> <span class="nf">query</span><span class="o">(</span><span class="nd">@RequestParam</span> <span class="nc">String</span> <span class="n">id</span><span class="o">);</span> |
| <span class="kd">public</span> <span class="nc">Person</span> <span class="nf">query</span><span class="o">(</span><span class="nd">@PathVariable</span> <span class="nc">String</span> <span class="n">id</span><span class="o">);</span> |
| <span class="kd">public</span> <span class="nc">Person</span> <span class="nf">query</span><span class="o">(</span><span class="nd">@RequestBody</span> <span class="nc">String</span> <span class="n">id</span><span class="o">);</span> |
| </code></pre></div></div> |
| |
| <p>Generally , simple data types, such as String and int, are transmitted in RequestParam or PathVariable, and complex data types are transmitted in RequestBody after being coded using JSON, to reduce problems cause by HTTP protocol restrictions on developers.</p> |
| |
| <h2 id="detailed-constraint-list">Detailed Constraint List</h2> |
| <p>Developers cannot use the following types to define APIs:</p> |
| |
| <ul> |
| <li>Abstract data structures, such as java.lang.Object, net.sf.json.JsonObject</li> |
| <li>API or abstract class |
| <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="kd">public</span> <span class="kd">interface</span> <span class="nc">IPerson</span> <span class="o">{...}</span> |
| <span class="kd">public</span> <span class="kd">abstract</span> <span class="kd">class</span> <span class="nc">AbstractPerson</span> <span class="o">{...}</span> |
| </code></pre></div> </div> |
| </li> |
| <li>Generic type |
| <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="kd">public</span> <span class="kd">class</span> <span class="nc">PersonHolder</span><span class="o"><</span><span class="no">T</span><span class="o">></span> <span class="o">{...}</span> |
| </code></pre></div> </div> |
| </li> |
| <li> |
| <p>A collection type of the preceding types or a set without a specified type, such as <code class="language-plaintext highlighter-rouge">List<IPerson>, Map<String, PersonHolder<?>>, List, Map</code>. such as <code class="language-plaintext highlighter-rouge">List<String>, List<Person></code> are supported.</p> |
| |
| <div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="kd">public</span> <span class="kd">class</span> <span class="nc">GroupOfPerson</span> <span class="o">{</span><span class="nc">IPerson</span> <span class="n">master</span> <span class="o">...}</span> |
| </code></pre></div> </div> |
| </li> |
| </ul> |
| |
| <p>Developers do not need to worry about the constraints. The program automatically checks them when it is started, and displays types as properties.</p> |
| |
| <h2 id="protocol-difference">Protocol Difference</h2> |
| <p>Although ServiceComb-Java-Chassis implements transparent transmission between protocols, there are slight differences between protocols due to the limitations of the underlying protocols:</p> |
| |
| <ul> |
| <li> |
| <p>Map, The key supports only string.</p> |
| </li> |
| <li>highway (protobuf restriction) |
| <ol> |
| <li>Null values cannot be transmitted over the network, including elements in Collection and array, and value in map.</li> |
| <li>The array and list with the length of 0 are not transmitted over the network. The receiver obtains the default value after decoding them.</li> |
| </ol> |
| </li> |
| <li>springmvc |
| <ol> |
| <li>Date cannot be used for the path or query parameter. Spring MVC stores toString in path and query, which does not match the swagger standard.</li> |
| </ol> |
| </li> |
| </ul> |
| |
| |
| </section> |
| |
| <footer class="page__meta"> |
| |
| |
| |
| |
| |
| </footer> |
| |
| |
| |
| |
| |
| </div> |
| |
| |
| </article> |
| |
| |
| |
| </div> |
| |
| |
| <script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script> |
| <div align="center" style="margin: 0 0;"> |
| <ins class="adsbygoogle" |
| style="display:block; border-bottom: initial;" |
| data-ad-client="ca-pub-7328585512091257" |
| data-ad-slot="3049671934" |
| data-ad-format="auto"></ins> |
| </div> |
| |
| <div class="page__footer"> |
| <footer> |
| <!-- start custom footer snippets --> |
| |
| <!-- end custom footer snippets --> |
| |
| <div class="container"> |
| <div class="row justify-content-md-center"> |
| |
| <div class="col"> |
| <ul> |
| <p class="header">Events</p> |
| <a class="acevent" data-format="square" data-mode="dark" data-event="random"></a> |
| </ul> |
| </div> |
| <div class="col"> |
| <ul> |
| <p class="header">Resources</p> |
| <li><a href="/docs/getting-started/">Getting started</a></li> |
| <li><a href="/docs/users/">User Guide</a></li> |
| <li><a href="/slides/">Slides</a></li> |
| <li><a href="/users/faq/">Common Questions</a></li> |
| </ul> |
| </div> |
| <div class="col"> |
| <ul> |
| <p class="header">ASF</p> |
| <li><a href="http://www.apache.org">Foundation</a></li> |
| <li><a href="http://www.apache.org/licenses/">License</a></li> |
| <li><a href="http://www.apache.org/events/current-event">Events</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| </ul> |
| </div> |
| <div class="col"> |
| <ul> |
| <p class="header">Contribute</p> |
| <li><a href="http://issues.apache.org/jira/browse/SCB">Report a Doc Issue</a></li> |
| <li><a href="https://github.com/apache/servicecomb-website/edit/master/_users/service-interface-constraints.md">Edit This Page on Github</a></li> |
| <li><a href="/developers/submit-codes/">Code Submit Guide</a></li> |
| <li><a href="/security">Security</a></li> |
| </ul> |
| </div> |
| <div class="col"> |
| <ul class="social-icons"> |
| <p class="header">Community</p> |
| <li> |
| <a href="mailto:dev-subscribe@servicecomb.incubator.apache.org" rel="nofollow"><span class="mail">Mailing List</span></a> |
| </li> |
| <li> |
| <a href="https://github.com/apache?q=ServiceComb" target="_blank"><span class="github">Github</span></a> |
| </li> |
| <li> |
| <a href="https://twitter.com/ServiceComb" target="_blank"><span class="twitter">Twitter</span></a> |
| </li> |
| <li> |
| <a href="/feed.xml" target="_blank"><span class="rss">Feed</span></a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="page__footer-bottom"> |
| <div>© 2024 Apache ServiceComb. Powered by <a href="http://jekyllrb.com" rel="nofollow">Jekyll</a> & <a href="https://mademistakes.com/work/minimal-mistakes-jekyll-theme/" rel="nofollow">Minimal Mistakes</a>.</div> |
| <div>All other marks mentioned may be trademarks or registered trademarks of their respective owners.</div> |
| </div> |
| |
| </footer> |
| </div> |
| |
| <script src="/assets/js/main.min.js"></script> |
| |
| |
| |
| |
| <script> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-101622733-1', 'auto'); |
| ga('send', 'pageview'); |
| </script> |
| |
| |
| |
| |
| |
| |
| |
| </body> |
| </html> |
