{"id":5925,"date":"2022-08-03T16:07:13","date_gmt":"2022-08-03T15:07:13","guid":{"rendered":"https:\/\/www.axpe.com\/?p=5925"},"modified":"2025-04-09T10:45:10","modified_gmt":"2025-04-09T09:45:10","slug":"pautas-generales-modelo-referencia-axpe-metodologia-api","status":"publish","type":"post","link":"https:\/\/www.axpe.com\/en\/pautas-generales-modelo-referencia-axpe-metodologia-api\/","title":{"rendered":"General guidelines in the reference model for the API methodology."},"content":{"rendered":"<div data-elementor-type=\"wp-post\" data-elementor-id=\"5925\" class=\"elementor elementor-5925\">\n\t\t\t\t<div class=\"elementor-element elementor-element-66181980 e-flex e-con-boxed e-con e-parent\" data-id=\"66181980\" data-element_type=\"container\" data-e-type=\"container\">\n\t\t\t\t\t<div class=\"e-con-inner\">\n\t\t\t\t<div class=\"elementor-element elementor-element-ffe96e3 elementor-widget elementor-widget-spacer\" data-id=\"ffe96e3\" data-element_type=\"widget\" data-e-type=\"widget\" data-widget_type=\"spacer.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t\t\t<div class=\"elementor-spacer\">\n\t\t\t<div class=\"elementor-spacer-inner\"><\/div>\n\t\t<\/div>\n\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<div class=\"elementor-element elementor-element-ce43a95 news-header elementor-widget elementor-widget-heading\" data-id=\"ce43a95\" data-element_type=\"widget\" data-e-type=\"widget\" data-no-translation=\"\" data-widget_type=\"heading.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t<h2 class=\"elementor-heading-title elementor-size-default\">General Guidelines at Reference Model for API Methodology<\/h2>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<div class=\"elementor-element elementor-element-91a6e5b news-header elementor-widget elementor-widget-heading\" data-id=\"91a6e5b\" data-element_type=\"widget\" data-e-type=\"widget\" data-no-translation=\"\" data-widget_type=\"heading.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t<style>.elementor-element-91a6e5b{display:none !important}<\/style>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<div class=\"elementor-element elementor-element-59a0c2b8 elementor-widget elementor-widget-text-editor\" data-id=\"59a0c2b8\" data-element_type=\"widget\" data-e-type=\"widget\" data-no-translation=\"\" data-widget_type=\"text-editor.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t\t\t\t\t\n<p class=\"wp-block-paragraph\">At AXPE&#8217;s <strong>API Expertise Cluster<\/strong>, we have defined an <strong>API Strategy<\/strong> aimed at establishing a set of <strong>Best Practices<\/strong> for API design.<\/p>\n<p>As part of our article series <strong>&#8220;AXPE Reference Model for API Methodology,&#8221;<\/strong> we will detail each aspect of this methodology. The first article will cover <strong>Introduction and General Guidelines<\/strong>, followed by topics such as <strong>Design, API Error Management, and Data Modeling<\/strong>.<\/p>\n<h5>Objectives<\/h5>\n<p>The <strong>primary goal<\/strong> of this methodology is to <strong>standardize and homogenize API structures<\/strong> to:<\/p>\n<ul>\n<li><strong>Simplify API consumption<\/strong> for both internal teams and external providers.<\/li>\n<li><strong>Facilitate decision-making<\/strong> in API design.<\/li>\n<li><strong>Accelerate development projects<\/strong> by ensuring a common language across teams.<\/li>\n<\/ul>\n<hr \/>\n<h5>What is an API?<\/h5>\n<p>An <strong>API (Application Programming Interface)<\/strong> is an interface exposed by a system to establish a <strong>technical and functional<\/strong> means of interaction with multiple systems. It acts as a <strong>contract<\/strong> and <strong>access gateway<\/strong> that enables system interoperability, with the following key characteristics:<\/p>\n<ul>\n<li>APIs must be properly <strong>visualized and exposed<\/strong> through an <strong>API Portal<\/strong>.<\/li>\n<li>They must be <strong>versioned correctly<\/strong>.<\/li>\n<li>API consumption must be managed through <strong>application permissions, consumption plans, and visibility settings<\/strong>.<\/li>\n<li>APIs must follow a <strong>recognized standard<\/strong> (e.g., OpenAPI 3, RAML, etc.).<\/li>\n<li><strong>Design and implementation<\/strong> must be <strong>decoupled<\/strong>.<\/li>\n<li><strong>API design and implementation must be in English<\/strong>.<\/li>\n<li><strong>API documentation may also be in English<\/strong>.<\/li>\n<li>Every API must have a <strong>mock version<\/strong>, a static response model that simulates real API behavior.<\/li>\n<\/ul>\n<hr \/>\n<h4>General Guidelines<\/h4>\n<h5><strong>1. Target Audience<\/strong><\/h5>\n<p>This methodology is designed for <strong>technical and functional teams<\/strong> with experience in API specification, particularly those using <strong>API Management tools<\/strong> such as <strong>Kong, Mulesoft Platform, or Azure API Management<\/strong>.<\/p>\n<h5><strong>2. Specification Structure<\/strong><\/h5>\n<p>An <strong>OpenAPI document<\/strong> can be structured as a <strong>single file<\/strong> or divided into <strong>multiple interconnected parts<\/strong> using keywords like <strong>.Schema, Object, $ref, etc.<\/strong><\/p>\n<p>We <strong>recommend<\/strong> naming the specification file <strong>openapi.yaml<\/strong>.<\/p>\n<p>At AXPE, we follow the <strong>&#8220;divide and conquer&#8221; philosophy<\/strong>, favoring <strong>small, modular, and highly specific structures<\/strong> that can be reused within a single OpenAPI document or across multiple documents.<\/p>\n<h5><strong>3. API Specification<\/strong><\/h5>\n<p>API specifications define <strong>practices, communication protocols, and structures<\/strong> that establish the contract.<\/p>\n<ul>\n<li><strong>Synchronous APIs<\/strong> must follow the <strong>OpenAPI<\/strong> specification.<\/li>\n<li><strong>Asynchronous APIs<\/strong> must use both <strong>OpenAPI and AsyncAPI<\/strong>.<\/li>\n<li>The <strong>OpenAPI version must be consistent<\/strong> across all APIs (<strong>always version 3<\/strong>).<\/li>\n<\/ul>\n<h5><strong>4. Language<\/strong><\/h5>\n<p>English is the <strong>mandatory language<\/strong> for defining API specifications.<br \/>This applies to <strong>URLs, objects, attributes, and documentation (descriptions, examples, etc.)<\/strong>.<br \/>The reason is that <strong>English is the predominant language in the global IT community<\/strong>.<\/p>\n<h5><strong>5. Examples<\/strong><\/h5>\n<p>Examples should be defined <strong>at the request and response level<\/strong> for each operation.<\/p>\n<p>They serve multiple purposes:<\/p>\n<ul>\n<li>Enhance <strong>understanding<\/strong> of API design for both API developers and API consumers.<\/li>\n<li>Enable the <strong>creation of API mock tests<\/strong>, allowing consumers to perform <strong>unit testing independently<\/strong> of backend development progress.<\/li>\n<\/ul>\n<p>While not <strong>mandatory (must)<\/strong>, we <strong>strongly recommend (should)<\/strong> providing clear and well-documented examples as part of the API design standard.<\/p>\n<h5><strong>6. Attribute Extension<\/strong><\/h5>\n<p>When <strong>custom attributes<\/strong> need to be defined, they must follow the format <strong>&#8220;X-&#8220;<\/strong> (e.g., <code>X-Request-ID<\/code>).<\/p>\n<p>Attribute naming must be aligned with the <strong>business entity data dictionary<\/strong>. A well-structured API <strong>must<\/strong> reference a <strong>catalog of business entities and their attributes<\/strong> to ensure alignment with <strong>business processes, products, and services<\/strong>.<\/p>\n<p>APIs may also contain <strong>technical or control attributes<\/strong> that are <strong>not part of business entities<\/strong>. These should be <strong>clearly identified<\/strong> to differentiate them from business-related information.<\/p>\n<h5><strong>7. Object Structure<\/strong><\/h5>\n<p>Each defined object must include a <strong>title attribute<\/strong>, with the value <strong>matching the object name<\/strong>.<\/p>\n<p>This allows validation tools (e.g., Spectral) to <strong>recognize and enforce predefined rules<\/strong>.<\/p>\n<h5><strong>8. Versioning<\/strong><\/h5>\n<p>API versioning is <strong>critical<\/strong> as business needs evolve.<\/p>\n<p>We follow <strong>Semantic Versioning<\/strong> (<a href=\"https:\/\/semver.org\/\" target=\"_blank\" rel=\"noopener\">semver.org<\/a>) to manage API evolution.<\/p>\n<ul>\n<li>API <strong>designers<\/strong> are responsible for <strong>defining and maintaining<\/strong> versions.<\/li>\n<li>The <strong>governance team<\/strong> ensures proper <strong>version control<\/strong> across APIs.<\/li>\n<\/ul>\n<p>Semantic versioning provides <strong>comprehensive coverage<\/strong> for tracking API evolution and ensuring compatibility.<\/p>\n<hr \/>\n<h4>Conclusion<\/h4>\n<p>At AXPE\u2019s API Expertise Cluster, we consider these <strong>general guidelines essential<\/strong> for establishing the <strong>fundamental principles<\/strong> of our <strong>Reference Model for API Methodology<\/strong>.<\/p>\n<p>In our <strong>next article<\/strong>, we will cover <strong>API design standards and best practices<\/strong>, including:<\/p>\n<ul>\n<li>HTTP <strong>status codes<\/strong> per verb.<\/li>\n<li><strong>Using POST for actions<\/strong> (event handlers\/controllers).<\/li>\n<li><strong>Header configurations<\/strong>.<\/li>\n<li><strong>URL structuring<\/strong> and resource modeling.<\/li>\n<li><strong>HATEOAS, pagination, and filters<\/strong>.<\/li>\n<\/ul>\n<hr \/>\n<p>This version maintains the <strong>clarity and technical precision<\/strong> required while making it <strong>structured and easy to read<\/strong>. Let me know if you need <strong>adjustments for tone or emphasis!<\/strong><\/p>\n\t\t\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<div class=\"elementor-element elementor-element-ed8ec7d elementor-widget elementor-widget-text-editor\" data-id=\"ed8ec7d\" data-element_type=\"widget\" data-e-type=\"widget\" data-no-translation=\"\" data-widget_type=\"text-editor.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t<style>.elementor-element-ed8ec7d{display:none !important}<\/style>\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<div class=\"elementor-element elementor-element-6891a7c elementor-widget elementor-widget-spacer\" data-id=\"6891a7c\" data-element_type=\"widget\" data-e-type=\"widget\" data-widget_type=\"spacer.default\">\n\t\t\t\t<div class=\"elementor-widget-container\">\n\t\t\t\t\t\t\t<div class=\"elementor-spacer\">\n\t\t\t<div class=\"elementor-spacer-inner\"><\/div>\n\t\t<\/div>\n\t\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t\t<\/div>\n\t\t\t\t<\/div>\n\t\t\t\t<\/div>","protected":false},"excerpt":{"rendered":"<p>En el Cl\u00faster de Experiencia en API de AXPE, hemos definido una Estrategia de API que tiene como objetivo detallar una serie de directrices de mejores pr\u00e1cticas para el dise\u00f1o de API.<\/p>","protected":false},"author":1,"featured_media":5937,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[22,23],"tags":[65,63],"class_list":["post-5925","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-press-room","category-analysis-and-trends","tag-integration-api","tag-modern-apps-api"],"_links":{"self":[{"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/posts\/5925","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/comments?post=5925"}],"version-history":[{"count":32,"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/posts\/5925\/revisions"}],"predecessor-version":[{"id":17771,"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/posts\/5925\/revisions\/17771"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/media\/5937"}],"wp:attachment":[{"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/media?parent=5925"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/categories?post=5925"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.axpe.com\/en\/wp-json\/wp\/v2\/tags?post=5925"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}