Last modified by Erik Bakker on 2024/09/02 16:11
From version 45.1
edited by Erik Bakker
on 2024/02/01 15:33
Change comment: There is no comment for this version
To version 26.2
edited by Erik Bakker
on 2024/02/01 08:34
Change comment: Update document after refactoring.

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -Documentation Portal Introduced
1 +fundamental-emagiz-introduction
Content
... ... @@ -1,78 +1,76 @@
1 1  {{container}}{{container layoutStyle="columns"}}(((
2 -In this microlearning, we will introduce the eMagiz documentation platform. The focus will be to address the fundamental concepts of the documentation platform. Please refer to other Fundamentals to learn more about related items and look at the relevant microlearnings available to learn how to work in eMagiz.
2 +In this microlearning, we will introduce the essential concepts of the eMagiz API Gateway. The focus will be to address the fundamental concepts of this pattern. Please refer to other Fundamentals to learn more about related items and look at the relevant microlearnings available to learn how to configure an API Gateway in eMagiz.
3 3  
4 4  Should you have any questions, please get in touch with academy@emagiz.com.
5 5  
6 6  == 1. Prerequisites ==
7 -* An interest in learning more about the eMagiz platform.
7 +* Some context on API Management will be helpful.
8 8  
9 9  == 2. Key concepts ==
10 10  All concepts are discussed in the section below.
11 11  
12 -== 3. Introducing the eMagiz documentation platform ==
12 +== 3. Introducing API Gateway ==
13 13  
14 -The eMagiz documentation platform is an add-on to the [[eMagiz platform>>doc:Main.eMagiz Academy.Fundamentals.fundamental-emagiz-introduction.WebHome||target="blank"]]. Within the documentation portal, we have four distinct categories of information for you to utilize. Should this be your first visit to the eMagiz documentation portal, we urge you to check out the tour. You can start this tour from the home page by clicking the "Show tour" icon in the bottom right-hand corner of your screen.
14 +The eMagiz API Gateway is the pattern in which a specific entry point is made available for external applications (users). These external applications can connect to this entry point via a series of operations. These operations are listed in a manner that allows this application user to retrieve data or provide data. Users & Roles are managed on a central level to control access to the various data sources.
15 15  
16 -=== 3.1 Academy ===
16 +[[image:Main.Images.Fundamental.WebHome@fundamental-api-gateway-introduction-1.png]]
17 17  
18 -In this segment, you can learn about the platform. To make your learning experience manageable, we have divided this segment into three categories. It starts with the [[Fundamental>>doc:Main.eMagiz Academy.Fundamentals.WebHome||target="blank"]] section that explains the eMagiz platform, the documentation portal, and the key features of the eMagiz platform for you to utilize.
18 +=== 3.1 Entry point for application users ===
19 +The entry point is a REST/JSON-based web service publicly accessible via the eMagiz Cloud for external application users. There is no other type of web service possible, and all the operations inside this web service are all REST/JSON based. In eMagiz, this concept translates into an All Entry flow type.
19 19  
20 -On top of that, we have the [[Microlearnings>>doc:Main.eMagiz Academy.Microlearnings.WebHome||target="blank"]] section that explains all components of the platform from a user perspective (i.e., what do I need to do to act eMagiz) in bite-size pieces. In this section, we divide the knowledge into various levels from Platform & Pattern [[Crash Courses>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.WebHome||target="blank"]] to courses per level of experience in the platform (i.e. [[Novice Level - eMagiz>>doc:Main.eMagiz Academy.Microlearnings.Novice Level.WebHome||target="blank"]]) so you can learn to use the platform in a structured way.
21 +=== 3.2 Operations ===
22 +An operation is defined as an entry point in the API Gateway that allows a specific type of interaction with the data exposed. For instance, a user wants to get the data for a particular order or create an order via this entry point. In this example, there will be a GET Order and a POST Order operation. The traditional HTTP operations, such as GET, POST, and PUT, are possible * see the below figure for the complete list.
21 21  
22 -Apart from the learnings in this section, it also details our [[certification program>>doc:Main.eMagiz Academy.Get Certified.WebHome||target="blank"]], including requirements and how to sign up for a certification.
24 +[[image:Main.Images.Fundamental.WebHome@fundamental-api-gateway-introduction-2.png]]
25 +
26 +=== 3.3 API Providers & Transformation ===
27 +There is a specific system connected to the operation for every operation, which gets the data or processes the data. That system, application, or service is geared towards that specific piece of data and may have its connectivity requirements, security requirement, or data structure. eMagiz will create a particular Exit Gate Flow type so that all these requirements can be appropriately handled. In the figure below the Control Tower, Exact, AFAS, and Address validator are the API providers.
23 23  
24 -=== 3.2 Store ===
29 +[[image:Main.Images.Fundamental.WebHome@fundamental-api-gateway-introduction-4.png]]
25 25  
26 -This segment documents all store components managed by eMagiz. We have divided these store items into two categories called [[accelerators>>doc:Main.eMagiz Store.Accelerators.WebHome||target="blank"]] and [[system connectors>>doc:Main.eMagiz Store.System Connectors.WebHome||target="blank"]]. Here, you can browse through (and search for) specific store solutions that you can use within your model. If you want more information on the store, please check out this [[fundamental>>doc:Main.eMagiz Academy.Fundamentals.fundamental-emagiz-store.WebHome||target="blank"]].
31 +Each operation can have a Gateway Message and a System message for the specific API. In this way, standard eMagiz transformation tooling is made available to handle content and format transformations in the API Gateway.
27 27  
28 -=== 3.3 Support ===
33 +[[image:Main.Images.Fundamental.WebHome@fundamental-api-gateway-introduction-5.png]]
29 29  
30 -This segment houses information that supports you in case you need to migrate via the help of our [[migration paths>>doc:Main.eMagiz Support.Migration Paths.WebHome||target="blank"]] and in case you are facing a problem in one of your environments, via the help of our [[RCA knowledge base>>doc:Main.eMagiz Support.RCA Knowledge Base.WebHome||target="blank"]]. On top of that, we provide an easy link to our support portal when you need to register a ticket with our support department. If you are still determining whether you need to register our ticket or communicate another way, please check out this [[fundamental>>doc:Main.eMagiz Academy.Fundamentals.fundamental-emagiz-assistance-needed.WebHome||target="blank"]].
35 +=== 3.4 Interaction type & error handling ===
36 +The API Gateway follows a synchronous pattern which means there is always a request being made to the web service, and that same web service will always provide you with a response. The web service will wait until the backend system delivering the response is ready to send that response.
31 31  
32 -=== 3.4 Release Information ===
38 +In all cases, the web service provides a specific response using HTTP response codes (the standard definition used). If a particular HTTP response code is returned that includes a specific error, then the requestor/application user is responsible for handling the returned error. That is by design as the synchronous nature of these request imply that the calling application needs to decide to continue to the next functional step or alike. In any case, it is different and specific for each application user.
33 33  
34 -This segment houses all our release information on the platform. Here, you can find the technical [[release notes>>doc:Main.Release Information.Portal.WebHome||target="blank"]] of the eMagiz platform, our [[infrastructure>>doc:Main.Release Information.Runtime Images.WebHome||target="blank"]], and our [[cloud>>doc:Main.Release Information.Cloud Templates.WebHome||target="blank"]] as well as more functional release blogs on the [[platform>>doc:Main.Release Information.Release Blogs.WebHome||target="blank"]] and the [[documentation portal>>doc:Main.Release Information.Documentation Portal.WebHome||target="blank"]]. This category intends to inform our users of what changes in every release so they can adapt.
40 +eMagiz does allow to influence some of these response codes by specific information per HTTP responses codes. Or provide custom responses.
35 35  
36 -=== 3.4 Navigation ===
42 +=== 3.5 Centralized User Management ===
43 +In the context of an API Gateway, user management means the mechanism whereby users are granted access to a specific set of operations. User Management in eMagiz can define users and roles. The user will have the access credentials to access the API Gateway in the first place. Options are OAuth2.0 or API Key. Users are assigned a role that defines to what operations access has been given. In this way, the access to the gateway is handled centrally, and the data exposed is adequately protected. Credentials are to be submitted to application users on a separate note.
37 37  
38 -There are three ways to find your way around the documentation portal. For each example we are going to navigate to the list of release notes that are published bi-weekly. The first one is by clicking through the various cards to get to the right information as shown below.
45 +=== 3.6 API Disovery ===
46 +External application users can discover the operations via an online Portal * the SwaggerUI technology is used for that purpose. In that online section, the user can see all the published operations. For operation, all the required information is displayed to understand how to connect to the API correctly. That includes the request and response definitions, parameters, naming, response codes, and many more. Once the credentials have been provided, the application user can try out the operation.
39 39  
40 -{{video attachment="left-panel-navigation-doc-portal.mp4" reference="Main.Videos.Fundamental.WebHome"/}}
48 +[[image:Main.Images.Fundamental.WebHome@fundamental-api-gateway-introduction-3.png]]
41 41  
42 -Secondly you could use the breadcrumb navigation on the top of the page to get to the same location as is shown below.
50 +=== 3.6 Architectural components ===
43 43  
44 -{{video attachment="breadcrumb-navigation-doc-portal.mp4" reference="Main.Videos.Fundamental.WebHome"/}}
52 +A simplified picture below illustrates the overall architecture of API Gateway in the eMagiz Cloud.
45 45  
46 -Thirdly you could use the navigation on the left of the page to get to the desired location.
54 +[[image:Main.Images.Fundamental.WebHome@fundamental-api-gateway-introduction-6.png]]
47 47  
48 -{{video attachment="card-navigation-doc-portal.mp4" reference="Main.Videos.Fundamental.WebHome"/}}
49 -
50 -=== 3.5 Search ===
51 -
52 -In case you are new or unsure how to navigate, as you don't know exactly where to look you can use the search functionality in the documentation portal to search for keyphrases. You can access the search functionality on the top-left hand corner of your page by typing in a keyphrase and pressing Enter. This will lead you to the overview of your search results. Once you have found the information in question you can click on the result to navigate to the page.
53 -
54 -{{video attachment="search-functionality-doc-portal.mp4" reference="Main.Videos.Fundamental.WebHome"/}}
55 -
56 -{{info}}
57 -* The search searches through all information available on the documentation portal.
58 -* Once you are in the search overview you can drill down to specific parts of the documentation portal (as demonstrated in the video)
59 -* Searching for partial words will not result in any hits.{{/info}}
60 -
61 61  == 4. Key takeaways ==
62 62  
63 -* The eMagiz documentation platform is an add-on to the [[eMagiz platform>>doc:Main.eMagiz Academy.Fundamentals.fundamental-emagiz-introduction.WebHome||target="blank"]]
64 -* It consists of four main categories of information
65 -** Academy
66 -** Store
67 -** Support
68 -** Release Information
69 -* You can follow a tour to understand better how to navigate the eMagiz documentation portal.
58 +* API Gateway can serve as a single entry point for all external or intern application users
59 +* API Gateway can simplify the IT landscape by offering a reusable entry point
60 +* API Gateway is a synchronous pattern by default
61 +* API Gateway leverages the standard capability of eMagiz around deployment, transformation, and business owner interaction
70 70  
71 71  == 5. Suggested Additional Readings ==
72 72  
73 -* [[Academy>>doc:Main.eMagiz Academy.WebHome||target="blank"]]
74 -* [[Store>>doc:Main.eMagiz Store.WebHome||target="blank"]]
75 -* [[Support>>doc:Main.eMagiz Support.WebHome||target="blank"]]
76 -* [[Release Information>>doc:Main.Release Information.WebHome||target="blank"]]
65 +* [[API Gateway Introduction>>https://www.emagiz.com/en/api-gateway-en/||target="blank"]]
66 +* [[Crashcourse API Gateway>>doc:Main.eMagiz Academy.Microlearnings.Crash Course.Crash Course API Gateway.WebHome||target="blank"]]
67 +* [[API Management>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.API Management.WebHome||target="blank"]]
68 +* [[Transformations in API Gateway>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Configuring the API Gateway.WebHome||target="blank"]]
69 +* [[Testing the API Gateway>>doc:Main.eMagiz Academy.Microlearnings.Intermediate Level.Testing API Gateway.WebHome||target="blank"]]
70 +* [[Advanced config API Gateway>>doc:Main.eMagiz Academy.Microlearnings.Advanced Level.API Management.WebHome||target="blank"]]
77 77  
72 +== 6. Silent demonstration video ==
73 +
74 +{{video attachment="fundamental-api-gateway-introduction.mp4" reference="Main.Videos.Fundamental.WebHome"/}}
75 +
78 78  )))((({{toc/}}))){{/container}}{{/container}}