@@ -452,6 +452,7 @@ <h1>meshcloud meshMetering API Docs</h1>
452452< li > < a href ="#data_types "> Data Types</ a > </ li >
453453< li > < a href ="#hypermedia "> Hypermedia</ a > </ li >
454454< li > < a href ="#versioning "> Versioning</ a > </ li >
455+ < li > < a href ="#deprecations "> Deprecation Policy</ a > </ li >
455456</ ul >
456457</ li >
457458< li > < a href ="#_common_data_formats "> Common Data Formats</ a >
@@ -680,38 +681,92 @@ <h3 id="hypermedia"><a class="link" href="#hypermedia">Hypermedia</a></h3>
680681< div class ="sect2 ">
681682< h3 id ="versioning "> < a class ="link " href ="#versioning "> Versioning</ a > </ h3 >
682683< div class ="paragraph ">
683- < p > meshStack applies versioning via custom Media Types. This allows custom versioning per resource.
684- As meshStack is developed and deployed continuously, this custom versioning per resource is the best
685- way for applying versioning. If e.g. the meshWorkspace response is modified in an incompatible way,
686- a new version will be provided for meshWorkspaces and all other resources are untouched.</ p >
684+ < p > meshStack’s meshObject API uses custom media types in the < code > Accept</ code > and < code > Content-Type</ code > headers for versioning.</ p >
685+ </ div >
686+ < div class ="exampleblock ">
687+ < div class ="content ">
688+ < div class ="paragraph ">
689+ < p > meshObject API versions each resource like < code > meshWorkspace</ code > or < code > meshProject</ code > < strong > individually</ strong > . This means
690+ you need to specify the specific media type corresponding to the endpoint you are calling.</ p >
691+ </ div >
692+ </ div >
687693</ div >
688694< div class ="paragraph ">
689- < p > If using a request body, such as when inserting a new meshProject via a POST endpoint,
690- the custom media type must be provided in the < code > Content-Type</ code > header. In case of a response body,
691- such as when requesting a list of all meshWorkspaces via a GET endpoint, the client should send
692- the custom media type in the < code > Accept</ code > header.</ p >
695+ < p > For example, when meshStack introduces a new version of the < code > meshWorkspace</ code > resource, this has no effect on other
696+ resources like the < code > meshProject</ code > . This allows the API to evolve in a granular way.</ p >
693697</ div >
694698< div class ="paragraph ">
695- < p > Examples for these headers are:</ p >
699+ < p > API clients must always set an < code > Accept</ code > header with the explicitly versioned resource media type.
700+ meshObject API will reject requests without an < code > Accept</ code > header using a < code > 406 Not Acceptable</ code > status code.
701+ The correct media type required for a resource is described in the corresponding Resource section in this documentation.
702+ For example, this is the media type required to access the < code > v1</ code > version of a < code > meshWorkspace</ code > resource:</ p >
696703</ div >
697704< div class ="listingblock ">
698705< div class ="content ">
699706< pre class ="highlightjs highlight "> < code class ="language-none hljs "> Accept: application/vnd.meshcloud.api.meshworkspace.v1.hal+json</ code > </ pre >
700707</ div >
701708</ div >
709+ < div class ="paragraph ">
710+ < p > Requests that need to send a body like < code > POST</ code > or < code > PUT</ code > must also set the < code > Content-Type</ code > header with the correct media
711+ type. For example, this is the media type required to POST a < code > meshProject</ code > :</ p >
712+ </ div >
702713< div class ="listingblock ">
703714< div class ="content ">
704- < pre class ="highlightjs highlight "> < code class ="language-none hljs "> Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1 +json;charset=UTF-8 </ code > </ pre >
715+ < pre class ="highlightjs highlight "> < code class ="language-none hljs "> Content-Type: application/vnd.meshcloud.api.meshproject.v2.hal +json</ code > </ pre >
705716</ div >
706717</ div >
707718< div class ="paragraph ">
708- < p > Which Media Type is required for which resource is described in the according Resource section.
709- If a request body is required and a different < code > Content-Type</ code > like simple < code > application/json</ code > is requested,
719+ < p > If a request contains a body and you specify an unsupported or unversioned < code > Content-Type</ code > like < code > application/json</ code > ,
710720the endpoint will return an error.</ p >
711721</ div >
722+ < div class ="exampleblock ">
723+ < div class ="content ">
724+ < div class ="paragraph ">
725+ < p > Endpoints that are documented as < code > preview</ code > endpoints in this documentation
726+ are subject to change and we are planning to introduce a new version < strong > without support for backwards compatibility</ strong > ,
727+ meaning, the preview version will disappear without prior notice!</ p >
728+ </ div >
729+ < div class ="paragraph ">
730+ < p > These endpoints have a media type with a < code > -preview</ code > suffix (for example,
731+ < code > application/vnd.meshcloud.api.meshbuildingblock.v2-preview.hal+json</ code > ).</ p >
732+ </ div >
733+ < div class ="paragraph ">
734+ < p > You are free to try those endpoints out, but we recommend to wait until the final (non-preview) endpoints are released
735+ before you integrate such endpoints with your infrastructure.</ p >
736+ </ div >
737+ </ div >
738+ </ div >
739+ </ div >
740+ < div class ="sect2 ">
741+ < h3 id ="deprecations "> < a class ="link " href ="#deprecations "> Deprecation Policy</ a > </ h3 >
742+ < div class ="paragraph ">
743+ < p > As we introduce new features and enhance existing functionalities, some API endpoints may become obsolete or outdated.
744+ Deprecating old endpoints is important to ensure the health and maintainability of the API.</ p >
745+ </ div >
746+ < div class ="paragraph ">
747+ < p > Explicit < a href ="#versioning "> Versioning</ a > provides API clients time to transition to newer versions of endpoints in a controlled manner.</ p >
748+ </ div >
712749< div class ="paragraph ">
713- < p > If the < code > Accept</ code > header is not provided, you may get the response of any version. Therefore please always
714- provide the < code > Accept</ code > header so you are guaranteed to get the resource in the expected format.</ p >
750+ < p > Deprecation follows a phased approach.</ p >
751+ </ div >
752+ < div class ="ulist ">
753+ < ul >
754+ < li >
755+ < p > < strong > outdated</ strong > : As soon as a new version of an endpoint becomes available, the old version is considered outdated but
756+ remains fully functional. API clients are advised to migrate to newer versions at their earliest convenience.</ p >
757+ </ li >
758+ < li >
759+ < p > < strong > deprecated</ strong > : We have announced an end of life (EoL) date when the endpoint will be removed from the API.
760+ API clients must migrate to newer versions before this date. Until this date, the endpoint remains fully functional.</ p >
761+ </ li >
762+ < li >
763+ < p > < strong > retired</ strong > : After the scheduled removal date, the endpoint is removed from the API and no longer available in meshStack.
764+ API clients using the old endpoint will receive an HTTP 406, HTTP 415 or HTTP 404 response as appropriate for the request.</ p >
765+ </ li >
766+ </ ul >
767+ </ div >
768+ < div class ="paragraph ">
769+ < p > Please refer to the < a href ="#deprecated-resources "> Deprecated Resources</ a > section for a list of deprecated and outdated endpoints.</ p >
715770</ div >
716771</ div >
717772</ div >
@@ -1048,14 +1103,14 @@ <h3 id="mesh_objects"><a class="link" href="#mesh_objects">meshObjects</a></h3>
10481103
10491104{
10501105 "_links" : {
1051- "meshchargebacks" : {
1052- "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks{?workspaceIdentifier,projectIdentifier,period,finalized,legacy,finalizedSince,cancelledSince}",
1053- "templated" : true
1054- },
10551106 "meshtenantusagereports" : {
10561107 "href" : "https://mesh-billing-url/api/meshobjects/meshtenantusagereports{?ownedByWorkspace,ownedByProject,isManaged,platform,platformType,platformTenantId,period,reportCategory,paymentMethodIdentifier,meshTenantId,finalizedAfter,cancelledAfter,status,showCancelled,sort}",
10571108 "templated" : true
10581109 },
1110+ "meshchargebacks" : {
1111+ "href" : "https://mesh-billing-url/api/meshobjects/meshchargebacks{?workspaceIdentifier,projectIdentifier,period,finalized,legacy,finalizedSince,cancelledSince}",
1112+ "templated" : true
1113+ },
10591114 "self" : {
10601115 "href" : "https://mesh-billing-url/api/meshobjects"
10611116 }
@@ -1265,7 +1320,7 @@ <h5 id="_list_meshtenantusagereports"><a class="link" href="#_list_meshtenantusa
12651320 "reportCategory" : "BILLING",
12661321 "platformType" : "Azure",
12671322 "platform" : "azure.prod",
1268- "platformTenantId" : "9611a4d2-0b3a-4c6d-82bf-c3483f276a47 ",
1323+ "platformTenantId" : "3ce47185-bb38-4da7-99eb-cb69e72c65dd ",
12691324 "version" : 2
12701325 },
12711326 "status" : {
@@ -1316,7 +1371,7 @@ <h5 id="_list_meshtenantusagereports"><a class="link" href="#_list_meshtenantusa
13161371 "reportCategory" : "BILLING",
13171372 "platformType" : "Azure",
13181373 "platform" : "azure.prod",
1319- "platformTenantId" : "c3c820b9-bd40-47ea-a4cf-86ebb85cb3dd ",
1374+ "platformTenantId" : "ff73e596-f784-4984-bad6-c99507cc30ad ",
13201375 "version" : 1
13211376 },
13221377 "status" : {
@@ -1644,7 +1699,7 @@ <h5 id="_get_meshtenantusagereport"><a class="link" href="#_get_meshtenantusager
16441699 "reportCategory" : "BILLING",
16451700 "platformType" : "Azure",
16461701 "platform" : "azure.prod",
1647- "platformTenantId" : "9611a4d2-0b3a-4c6d-82bf-c3483f276a47 ",
1702+ "platformTenantId" : "3ce47185-bb38-4da7-99eb-cb69e72c65dd ",
16481703 "version" : 2
16491704 },
16501705 "status" : {
@@ -1852,7 +1907,7 @@ <h5 id="_list_meshchargebacks"><a class="link" href="#_list_meshchargebacks">Lis
18521907 "apiVersion" : "v3",
18531908 "metadata" : {
18541909 "name" : "2025-04-01Z/testPartner:testWorkspace:testProject",
1855- "createdOn" : "2025-04-02T12:09:54.593505400Z ",
1910+ "createdOn" : "2025-04-09T12:08:16.210065300Z ",
18561911 "finalized" : true
18571912 },
18581913 "spec" : {
@@ -1914,7 +1969,7 @@ <h5 id="_list_meshchargebacks"><a class="link" href="#_list_meshchargebacks">Lis
19141969 "apiVersion" : "v3",
19151970 "metadata" : {
19161971 "name" : "2025-03-01Z/testPartner:testWorkspace:testProject",
1917- "createdOn" : "2025-04-02T12:09:54.594497500Z ",
1972+ "createdOn" : "2025-04-09T12:08:16.210990500Z ",
19181973 "finalized" : true
19191974 },
19201975 "spec" : {
@@ -2207,7 +2262,7 @@ <h5 id="_get_meshchargeback"><a class="link" href="#_get_meshchargeback">Get mes
22072262 "apiVersion" : "v3",
22082263 "metadata" : {
22092264 "name" : "2025-04-01Z/testPartner:testWorkspace:testProject",
2210- "createdOn" : "2025-04-02T12:09:54.593505400Z ",
2265+ "createdOn" : "2025-04-09T12:08:16.210065300Z ",
22112266 "finalized" : true
22122267 },
22132268 "spec" : {
@@ -2548,7 +2603,7 @@ <h5 id="_put_meshresourceusagereports"><a class="link" href="#_put_meshresourceu
25482603</ div >
25492604< div id ="footer ">
25502605< div id ="footer-text ">
2551- Last updated 2025-04-02 12:08:26 UTC
2606+ Last updated 2025-04-09 12:06:25 UTC
25522607</ div >
25532608</ div >
25542609< link rel ="stylesheet " href ="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.6/styles/github.min.css ">
![github-merge-queue[bot]](https://avatars.githubusercontent.com/u/9919?v=4&size=40){kind=avatar}
0 commit comments