Transcription
Good evening, colleagues!
We are starting our open lesson at 8 o'clock. I think it's the right time to begin. I hope many of us have already gathered.
To start, I would like to ask if you can see and hear me. Please, as per our tradition, put some signs in the chat to let me know if you can see and hear me—perhaps some plus signs.
Great, thank you! This is how we usually check at the beginning of our sessions to ensure everything is working fine and that the students can hear us.
I want to warn you right away that as your lecturer, I can be managed through this chat. You can ask me to speak louder or softer, slower or faster, simpler or more complex. Unfortunately, this is the only channel of feedback from you to me. So, I will be monitoring the chat to ensure I don’t get carried away in one direction.
If you have any technical requests—louder, softer—please feel free to express them.
Today, we have gathered to participate in an open lesson from the Systems Analyst course specialization and to discuss one of the topics. Besides learning how to design your own systems, you will also see how our open lessons look in our office.
My name is Valery Lvov. I am the lead systems analyst in the Mir platform team, which you may know from the fast payment system, for example. Here, during my vacation, I work on courses at the Faculty of System Analysis, teaching both Basic and Advanced courses, as well as at the Testing Engineers Faculty in the Basic course, where I teach testers about requirements and the organization of development processes.
To make our session more interesting, please write something about yourself in the chat. I am curious about the people who will be listening to me today. Are you already working as a systems or business analyst? If so, for how many years? If not, which IT sector are you coming from? I assume you might be architects, developers, or testers, as these are common paths into systems analysis. But if you are not from IT and are just planning to jump in, please let me know. It will be very interesting.
Thank you for sharing! If, for some reason, you don’t want to write about yourself, please share your city, the weather there, and your mood on this Friday evening.
While I look at the statistics, I want to mention that there is about a 5-second delay in the YouTube broadcast from what I say to what you hear. Therefore, I will see the chat about 10 seconds later.
Unfortunately, the rules for today’s webinar are that we try to avoid a banal lecture. We keep it quite simple, but we repeat these points every time.
First, we actively participate because this is not a lecture; it’s not a recorded lecture on YouTube. This is an interaction between the teacher and students, or between students themselves. The only way for you to interact with me is to write your questions in the chat. I will glance at it periodically and answer your questions when I have a pause.
This is not a typical webinar format for us because we usually meet in Zoom, turn on microphones, and some even turn on cameras. We work as if we are in a regular seminar where we all gather in person. The teacher shares information, students ask questions, and then they start working hands-on, correcting each other. The teacher explains how it should be done, and we follow this format. Sometimes we gather for mobbing sessions where one person shares their screen while others watch, and so on.
So, usually, it’s some live communication. Unfortunately, YouTube only allows broadcasting in one direction. However, I can read where you are coming from. Many of you have written that you have worked for two years in systems analysis or business analysis.
Great! We have a tester and a developer here, it seems. Only one person mentioned that they are completely new, but I think it won’t be too difficult for them today because we will try to speak simply.
I apologize; I accidentally skipped one slide.
The agenda for today’s webinar is as follows:
We will spend 5 minutes getting to know each other and the program, and then we will move on to the technical part.
We will briefly discuss what REST and API are, assuming you already know a little about them. We will talk about where a systems analyst should see the need to design an integration, what they should have on hand to start designing the API or integration with paper and pencil.
What does API design entail? What should the analyst do to pass their work to the developer, and how should they document their work so that clients can use it?
We will spend about an hour on this. After that, we will return to discuss the course team and the course program because this specialization course differs from the Advanced and Basic courses.
As a bonus, I will provide a spoiler about career information—whether there are systems analysts in the market.
Then, there will be a large block for answering questions and summarizing what we have learned, what we haven’t learned. Again, you can vote in the chat with likes or dislikes, pluses or minuses, to show if you like the agenda and the topic of our webinar.
So, what is Otus?
It’s a fairly old organization that has been working in the educational market for over five years. Initially, Otus worked with IT specialists at the Middle level, enhancing them to Senior level. However, recently, there has been a demand from non-IT specialists or IT professionals from other fields who also want to learn with us.
As a result, we have launched a series of courses for beginners, including Basic Systems Analyst and Basic Tester courses, as well as a large specialization program for Systems Analysts from scratch.
I remind you that Otus has an educational license, and therefore, a number of courses, including this specialization, allow you to obtain a state diploma in professional retraining.
Believe me, this is wonderful! Besides gaining knowledge, skills, and experience, you will also have a beautiful piece of paper—if I’m not mistaken, it’s red.
In these five years, we have worked with 458 students, and I am among them as a teacher. Many of you may know my name, and that’s great!
You can open a special page on the Otus website to see who is currently working as a teacher. The page is endless and can be read for a long time. I sometimes glance at it out of curiosity.
Now, let’s stick to the timing.
The topic of our lesson today is how an analyst can design their own REST API.
Here, every word seems important because, first of all, it’s the analyst who designs it, not the developer. The developer will develop based on the information we provide. The tester will test the work of the analyst, who will design and pass it to development.
The second important word is "own" REST API.
REST API integration involves integrating systems with each other. Naturally, it can go in both directions: either someone provides their interface, and we connect to it, or vice versa—we provide our interface to someone else, and they connect to us.
We will consider the second option, where we decide to expose some functions externally and create an interface that will be used by either our external clients or other modules or systems within our company.
By the way, the API can be a commercial product from which we can charge money, or it can be used by other modules or systems within our company.
So, we will focus on this specific case, although the topic of integration is vast and can be discussed extensively.
Since we cannot cover everything in this short session, I will make some assumptions that you are already experienced individuals. Therefore, I assume you know what system integration is, that it involves data exchange, and that there is an interface for integration called API.
You probably also know that the golden star, REST, is currently the best option for integration and is an industry standard.
I will briefly explain what it is, as it’s impossible to cover everything in an hour, including using someone else's integration, writing your own, designing, testing, data buses, and other architectural styles of integration.
So, we will only talk about one aspect.
The goal of our session is for you to try, touch, and experience a trial lesson, and to see how we do things here.
Naturally, the practical goal is for you to be able to say after an hour, "Now I can write in my resume that I know how to design APIs."
But the main goal is for you to simply experience being students for this hour and see how everything works.
Let’s move on to the goals of the webinar.
I want you to be able to say after an hour that you know where to find the information needed to design system integrations.
Secondly, I want you to be able to formulate a beautiful URL and its description so that anyone reading my documentation will say thank you.
And thirdly, I want you to know how to write to the developer who will work on your task, what they need to write, and how to make it so that they say, "Okay, thank you, I will go to work."
I believe these artifacts of an analyst's work at this stage will be in demand by the team, and the team will thank you.
Olga asks how to determine whether to design your own API or connect to someone else's.
If you have parity systems—just two identical ones—you can agree on who will connect with whom. You can even flip a coin to decide who will provide the interface and who will connect.
But the rules are such that if you have a service that will be used by many people, internal systems, external integration partners, or external clients, then you will likely need to provide the interface for everyone to use, not the other way around.
So, you won’t need to draw 10,000 adapters to someone else's interfaces for the same function.
If you have a service that you want to share with the world, then you need to create that interface.
The case study we will work on today involves designing our work.
Since I have worked in banks for a long time, I took an example that is very close to me.
Let’s assume we have a money transfer system in our educational bank that allows sending money, for example, by phone number.
We are currently developing or have developed a module called the Fraud Monitoring subsystem.
Fraud Monitoring is a system that works with fraudsters, maintains blacklists of bad people, and determines through certain actions whether a client is a fraudster. It collects money and gives recommendations on whether to check or not, or what limits to set.
In short, it works with fraud.
Logically, this Fraud Monitoring system does three things: it checks if a client is in a black, gray, or white list when they try to do something, gives recommendations during transactions, and has algorithms that allow it to identify fraudsters based on their behavior.
How this works internally is not important for us right now.
We are writing the integration of this system with someone else.
This is a very simplified case, of course; everything works much more complex and interesting.
But first, I cannot reveal the secrets, and second, it doesn’t matter right now.
We need to work on one or two things in an hour.
So, let’s take a breath and start designing the integration of the monitoring system with someone else.
Currently, we are at the design stage of something.
In my worldview, I have depicted the software development process.
First, requirements are identified, then the analyst, architect, or someone else designs the future system. After designing, they pass everything to development, where someone writes the code.
Once the code is written, the entire team tests what has been written, checking how closely the result matches the previously identified requirements.
If everything is okay, then they deliver it, meaning they transfer the production landscape to other servers.
The process can look different, but we are currently in the first half of the requirements.
We need to design and pass it to development.
So, we arrive at work, thinking about what to do, and suddenly remember, "Oh, we forgot about the integration."
The monitoring module will not live in a vacuum; someone will use it.
The analyst thinks, "I must not forget such an important thing," and looks around for signs in nature that he needs to see this integration.
In my opinion, there are four things where it will definitely manifest.
First, it’s the context diagram that describes what is inside the system and what is within its reach.
Second, it’s the description of business processes or business process diagrams.
These are requirements written in words, and if a systems architect has already worked, there may be component or other diagrams showing that your system is connected to someone.
First, as a systems analyst, you probably drew a context diagram at the very beginning of the project, reflecting the scope of your future work—what is included in the system.
This is the innermost circle, where it is written that the system will consist of modules A, B, C, D, etc.
In the second circle, there is something called an onion diagram, where you, as an analyst, will learn to draw all the components with which the system will interact—what is not included in it but interacts with it.
Such a diagram is drawn at the beginning of the project to understand what is in our area of focus and what is outside of it, so nothing is forgotten.
Let’s assume the analyst drew it together with the project manager.
What do we see from such a diagram?
We see that there are some people working in the system, some group of analysts, and several other systems that interact with our fraud system.
Okay, there’s an analytical showcase, but it seems that some data will be exported to it—a feed from the Central Bank, a feed of fraudsters that the higher authority provides.
Okay, we will need to load client data.
It’s clear that some scoring system will exchange data with us.
Looking at the diagram, we see that we need to create integration gateways with systems 1, 2, 3, 4, and 5.
Great! We need to take note of that and not forget to do it.
From the context, it’s clear that card transfers are not related to our security system.
For some reason, we have excluded them, and a decision was made that the client system for working with legal entities is also not in our area of focus.
So, we won’t pay attention to it.
We know what we need to do and what we don’t need to do.
The second place where we can see the presence of integration is the description of business processes.
For example, here is an example of a BPMN diagram that describes a business process in German notation.
If you take a business process BPMN or a connectivity diagram, you can also see that there is interaction with other systems.
Here, the workflow chain describes what needs to be checked for the recipient, what events need to occur, transferring money, and sending something.
The analyst wrote this down every time, thinking about where the action occurs—transferring money happens in one module, checking the recipient against the blacklist happens in the anti-fraud system.
He pre-recorded that there will be interaction with the blue square called the system.
Looking at the business process diagrams, it’s immediately clear that there is interaction with external systems, meaning we need to integrate.
The third place is if the architect drew a component diagram of your future scheme.
Here, everything is simple; they did it for you.
Here is your fraud monitoring system, and here are the feeds from the Central Bank that it will load into us and other banks.
And here is the system interacting with us that takes some data from us.
This notation, called a lollipop, shows who provides the interface and who will use it.
In this case, the Central Bank provides the interface, and we embrace it, meaning we use this interface.
Here, we are the ones providing the interfaces, and those guys are using them.
Thanks to the architect for thinking ahead and waving a red flag at us, reminding us not to forget to work on it.
Please look at the requirements.
Think if there are any markers because we are not developing a standalone system but an integration.
What will the integration be with? What other module or system?
Can you highlight key words and write them in the chat?
Meanwhile, I see Vladimir writing the key word "request."
Great! There are entire blocks of verbs and nouns that show that we need to make a request from the fraud monitoring system to the fraud scoring of the recipient.
Awesome!
In the last sentence, we need to load transaction data into the fraud monitoring system.
Let’s highlight that with a highlighter and see that the requirements mention integration with someone.
So, we have four places where we can see signs that integration is needed: the context diagram, the description of business processes, the component diagram made by the architect, and finally, just the requirements written in text.
We need to extract verbs and nouns from them and then think about what to do with them.
We have completed the first part.
It seems simple; we have learned to do something new.
Let’s move on to the design phase.
To start designing our API, what do we need?
First, I assume that as analysts, you may have developed an information model with the architect.
This is also called an ER diagram or entity-relationship diagram.
This model shows what information entities will describe your business activities.
This resembles a database.
Now we will need it to understand what information we will be working with.
I remind you that we are currently working with an information system.
An information system is one that accumulates, processes, stores, and returns information.
We see that we have some information objects over which we need to perform some actions.
From the requirements written above, we can easily understand what actions need to be performed.
In the first case, we need to read the rating and return it.
In the second case, we need to write the rating.
These actions resemble CRUD operations: Create, Read, Update, Delete.
As analysts, you have developed an ER diagram either earlier or now.
If you didn’t have one, you will learn to do this in our courses.
Secondly, you need to write the input and output data descriptions, at least in business terms.
Then, you will need to write the operations on these data within the system.
Let’s go back a bit.
What is the description of the input and output data in business terms?
Look, it’s simply written: "Fraud scoring of the recipient."
To request it, we probably mean to get the fraud scoring.
We see that this is some numerical indicator, like 0, 1, 2, which shows the reliability or unreliability of the client.
These are the key words here.
What data needs to be put into the system?
What data needs to be extracted from it?
If there were something else besides scoring, it would probably be listed, such as saving the last name, first name, patronymic, date of birth, registered address, etc.
We need to understand what needs to be loaded and what needs to be read.
Okay, so we have the ER diagram, data description, and an understanding of what actions will be performed with this data inside the system.
Let’s open the ER model drawn by you as analysts.
Yes, for our anti-fraud system, since we are writing the interface for it, the interface will pull some information objects from our side called resources.
So, we need to design these resources.
To do this, we need to understand what information is stored in the anti-fraud system.
There is a separate system for transfers, and it has its own information model.
I quickly sketched a very simple version of this ER diagram to make it clear to everyone while reflecting our case.
I have three information entities: the client, which I previously wrote will be a physical person, the client who makes transfers, and transfers associated with the banks to which the transfers are sent in the anti-fraud system.
I believe that for the client, we only need to store their identifier, phone number, and some number or string describing their scoring—good client, bad client, suspicious or not.
It seems that’s all.
In this case, I don’t think we need to store the client’s last name, first name, patronymic, phone number, address, account numbers, or anything else.
For fraud, this information seems sufficient, plus a collection of transfers associated with this person.
So, the system itself can use, for example, the history of transfers over the last day to recalculate their rating.
Let’s call this model number one.
Since it’s too simple, I sketched model number two.
Let’s assume we decided to store information differently.
In this case, our anti-fraud system stores the complete profile of the client, including their ID, full name, address, and some other necessary data that I didn’t bother to list.
This client profile is linked to a short anti-fraud profile, rating, and update date.
Okay, if we decided to work with such a system, let’s work with this information model.
For example, we will have a simple case and a slightly more complex one.
Please write how you are keeping up with the thought process—faster, slower, simpler, or more complex.
The client is a physical person who makes a transfer or receives a transfer.
I don’t know; it seems to me that we are not considering legal entities right now, just physical ones.
I also assumed that the transfer could be within the same bank because otherwise, we would need some banking details.
Vladimir asks about the ratio of 1:1.
This separation is for speeding up access to the fraud profile table.
No, it’s to show two-level resources in the model.
I think the first option is more workable, but let’s also work on the second one.
Again, this is a training example, so please treat it critically but not too harshly.
We have come up with the ER diagram, identified the information entities, and thought about the resources.
What’s next for designing the integration?
We need to write the interaction between one system and another, preferably in the form of a picture.
The best way to do this is to use a sequence diagram, which you see here.
This is possibly the most popular diagram in the world.
It allows you to explain anything to someone who doesn’t understand any notations.
Vertical columns represent the participants in the process: the client, the money transfers, the anti-fraud system, and even a database, although that’s already internal.
Arrows show requests, and dotted lines show responses.
It’s clear that within the integration, someone sends requests and waits for a response.
These can be different; it can be just a response or a substantive one.
On this diagram, it wasn’t necessary to draw the physical client, and it wasn’t necessary to draw the database because that’s too general.
The interaction with the client is too general, while the interaction with the database is too deep.
We are interested in the columns of the anti-fraud system and how it interacts with itself.
Once again, I remind you that in normal business language, we should simply write what each system wants from the other.
The money transfers want to get a rating from the anti-fraud system.
So, the request could be something like, "Give me the rating for the phone number."
Here, we don’t need to detail how the request will look, what parameters it will have, what headers will be sent, or what bytes will be sent.
We should write in simple, understandable business language what one system wants from the other.
The key words here are "Give" and "phone number."
So, the request will be something like, "Give me something," and the data being passed is just one line with the number.
This is important.
In response, the system says, "Here’s the rating."
The rating is probably also just one number.
Vladimir suggests adding a user check.
If the user is not found, then the diagram will be more complex.
We need to first check for the user’s existence, then check, for example, if they are a fraudster.
We can draw some case scenarios, but that’s not about integration; it’s about process description.
However, that’s a great suggestion.
The second request we see here is when a person makes a transfer after all checks have been completed.
The system says, "Add this amount to their profile."
The anti-fraud system adds it internally, and in response, it can simply say, "Okay, done."
In this case, the response will be extremely concise: "Okay."
What’s next?
We have written the requests and responses, the order in which they occur, and what business data is transferred in each direction.
In the second case, the business data includes the phone number and the transaction amount.
Great!
We are almost ready to start designing.
However, I must remind you, in case someone doesn’t know, what REST is.
Some people might ask what API is.
I don’t know which is correct; I was taught to say API.
In English, it’s called Application Programming Interface, and in Russian, it’s called интерфейс программного взаимодействия.
But I think it’s good to call it an interface for inter-program communication when two computers or applications communicate with each other.
There are interfaces between computers and humans, and there are also interfaces between computers.
Our task is to design such interfaces so that two computers can communicate quickly and effectively.
In our case, we will use the RESTful API over HTTP.
The document format will be JSON because it’s simple and beautiful, and I chose it.
The transport protocol will be HTTP because it’s simple, beautiful, and easy to explain.
In three-quarters of cases, you will encounter this implementation.
The HTTP protocol is interesting for us analysts because it has verbs that define actions.
Today, we will look at GET and POST, for example.
There are also status codes that indicate whether a request was good or bad.
In the Advanced course, you will analyze what WSDL is, look at XML, and other types of integrations, such as shared databases, buses, and brokers.
Today, we clearly won’t have time for that, and we don’t plan to.
The second word, REST, I separated into two words because an API can be RESTful or not.
REST is not a specific protocol; it’s not a standard; it’s a style of development, a style of designing integrations between systems.
If your integration meets these five mandatory requirements, then there’s a high probability that your integration will work faster, be more reliable, easier to update, and easier to maintain.
We do this not because it’s trendy but because there are business benefits.
For an integration to be considered RESTful, five conditions must be met.
First, it’s client-server interaction.
Logically, yes, the client sends a request, the server processes it, and returns a response.
Second, it’s called stateless in English, which translates awkwardly to "absence of state" in Russian.
This means that the server, after answering your question, forgets and does not remember that we asked a question.
If you need a reminder, I can help you figure out how to play your smart speaker and check if it’s in sleep mode or full mode.
The third criterion is that clients or intermediate nodes can cache requests to reduce traffic.
Great, but that’s not for us today.
Fourth, uniform interface: when we use the same resources for the same purposes, we access them differently.
Finally, the system must be layered, and we should only see one layer that we are accessing.
An example of the fifth point is that the client only sees the money transfer system and does not know what is on other layers behind it.
The money transfer system only sees the anti-fraud system and does not know what is beneath it—what kind of database it is, how it works, etc.
It’s not their business; the interface is there, so use it.
If we design something that meets these five requirements, we can cut ourselves a star from foil and say that we are RESTful and be proud of our development.
So, let’s prepare, take a breath, and drink some coffee for courage.
Let’s start designing the system in a stylish, trendy, and youthful way.
After all, if you are designing an interface, you should do it in a way that allows you to communicate effectively.
From the analyst's perspective, designing an API means coming up with a request and a URL that, upon looking at it, another person can understand in five seconds what your service is, what your method interface is, and what this thing represents.
I intentionally blurred the picture; these are not glitches.
Looking at this line, another person who will integrate with you should be able to say, "I understand what this is."
Please give me this thing.
If you have a large interface with dozens or hundreds of different methods exposed for different cases, it’s important for the person to quickly scan the table of contents and say, "I need this one, this one, and this one," and then look at their descriptions, or maybe not even look because they already know everything.
So, our main task is to come up with a good, beautiful URL and a verb for it, and then add some meat to it.
Since this is an information system, we have information objects and actions to perform on them.
Where will we get the description of what we need to work on and what actions need to be performed?
From those very requirement descriptions and sequence diagrams, for example.
Our action is to request, or more precisely, to get the scoring from the fraud monitoring system.
Let’s get the scoring of the client.
Experienced people, please suggest some URLs and requests that allow us to get the client’s scoring from our system.
We will try to figure it out.
First, you will warm up and come up with your own version, and we will discuss it.
I suggest the simplest option.
If you like it, just put a plus.
If you don’t like it, let me know why.
Let’s take a 30-second pause.
Adding search parameters is a good idea.
Valentin suggests a request.
I see the request "GET clients."
For me, this reads as "Give me clients."
If you send this request before the question mark, it means I want to get all the clients in the system.
This is too much because I only need the profile of one person.
Moreover, I don’t need the profiles of these people; I need to get the fraud scoring.
So, we will discard this option; it’s definitely not what we want.
I suggest option number two: "GET clients/ID."
For those who don’t quite understand what’s being discussed, this is a request when we want to get information about one specific client.
The resource name is "clients," which I derived from our information model.
Remember, there were clients, transactions, and banks, but I assumed that this would be how my request looks.
This is a specific client’s information.
Valentin says this is a normal option if the client entity contains what we need.
Thus, we can get information about a specific client.
In Russian, this request reads as, "Give me the entire profile of the client with this identifier."
Great!
Let’s rewind a bit to our information model and think about if it looks like this, with the client entity drawn on the left.
Then this request is exactly what we need to get.
We need to get one instance of this client.
But if our information model is different and there is a client and a separate fraud profile associated with them, then the request will probably look different.
Because the example is too simple.
I suggest this option: "GET clients/ID/fraudScore."
Again, the word "GET" means "Give."
Here, we have the client entity, and after the slash, we have the identifier of the client we are talking about.
Then, after another slash, we have the related entity, "fraudScore."
In Russian, this request reads as, "Give me the fraud score of the client with this identifier."
I looked at this request, and I understood that it allows me to get the fraud score of the client with the specified ID.
We can discard the first option because it’s not worthy of an analyst.
The second option is quite suitable for the first information model, and the third option is suitable for the second information model where we have a separate client entity and a separate fraud scoring entity.
I think that’s great!
Please put likes and subscribe to the channel if you think there’s logic in my words.
As a good practice, the request should be so good that it can be read in five seconds without looking at the documentation.
It should be clear what it does.
In the URLs, you should not use verbs.
You have the verb "GET," which is already a service verb in HTTP.
We will only operate with nouns: the entity, the identifier, and another entity.
This kind of URL can be nested when we get one entity and want to get a related entity.
In this case, I have two levels: clients and their associated fraud scores.
One level, as before, is fine; two levels are normal; three levels are worse but acceptable.
Please do not create more than three levels of nesting.
First, it’s hard to understand who is related to whom, and second, you will likely make mistakes in your descriptions and those who will be writing integrations to your system.
So, three is a good maximum.
How to name your resources?
You should name them similarly to how your information entities are named in the ER diagram, using Latin letters and English words.
Please be careful with this.
I hope you have a glossary that you created at the beginning of the project.
We teach you to do this.
A glossary is a dictionary that allows all project participants to speak the same language.
This is also important, and you should use terms described in this glossary.
It may happen that physical clients are called "clients" in one department, "users" in another, and "senders" or "receivers" in a third.
It’s good that you use the same language to describe the same entity.
A bad example for naming a resource is the word "client," which I used.
In my training example, it’s not clear who the client is.
Who uses the bank’s services?
There are physical clients and legal entity clients.
We need to distinguish them.
From the perspective of client-server architecture, a client is something else entirely.
There are many different words hidden under the term "client."
So, this is one of the worst words to use.
Now, let’s move on to the questions about the other ER diagram.
I would suggest a different name for the table.
Listen to Vladimir; I never mentioned the word "table."
I haven’t designed my database yet.
What I see are information entities describing our objects in business language with their business attributes.
I haven’t designed tables or defined the relationships between them yet.
Although we are getting there.
I haven’t assigned table names or specified what columns we will have.
For now, this is not a table; it doesn’t contain operational information.
Okay, I would suggest a different name for the table: "GET fraudProfile/ID."
Okay, I accept that instead of "client," it should actually be "fraudProfile."
Yes, the ID is usually in curly braces to make it clear.
And yes, "fraudScore."
I accept that.
The word "table" was not my intention.
Dmitry writes, "What’s wrong with this link: GET client/fraudScore/ID?"
It’s a good link, but it will be read differently.
It means, "Give me the fraud score for the client with this ID."
In our case, the identifier refers to the client, not the fraud score.
So, if it’s "client/ID/fraudScore," that’s good.
If it’s "GET client/fraudScore/ID," then it’s not correct.
Valentin, thank you for the correction.
Let’s look at the example I complicated.
It’s easy to read, quick, and has no verbs except for "GET," which is a service verb.
It has no more than three levels.
The words "client" and "fraudScore" are written in singular form.
You can use plural, but then please use it consistently throughout your API.
Also, I hope that the analyst who came up with this client used the glossary, and it’s clearly stated that the English word "client" refers to a physical person using our bank’s services.
Now, let’s see the magic.
Remember, I said that designing an API is essentially describing a good URL and coming up with a good description for it.
We took this and made it happen.
The main work is done, but it’s just the skeleton because we still need to come up with what our requests and responses will look like.
I remind you that in HTTP GET requests, there are two important things: the request line and the headers that accompany it.
In the response to a GET request, there is also a response line, headers, and most importantly, the information we requested, which is the body of the response.
In my case, this will be JSON.
How might the request look?
Well, the GET client/ID fraudScore can be written as an example.
Just in case someone doesn’t understand how this will look, let’s agree that technical headers are undoubtedly important.
The protocol cannot function without headers, but headers contain operational information for transport, mainly for transport, and as system analysts, we are generally not interested in them.
Unless we are passing some business information in them.
Let the developer or their framework handle the headers; they are not our concern.
Let’s focus on the request.
We have already written it, and it has a beautiful name.
What will be in the response?
In the response, there are two things: the response line from which we extract the response code, which is very important, and the body, which we requested.
If anyone finds it easy now, I invite experienced people to recall what response code 418 means.
For those who don’t know, I will briefly go over it.
There are different response codes that clearly indicate what the server is telling us.
Responses starting with 200 indicate a positive response, and response 200, which translates simply as "OK," means that yes, you asked me well, and I found the information.
Here’s the response.
There’s also a scenario where we requested information about a client who is not in our database.
In this case, we need to respond correctly to our requesting client.
We should say, "Sorry, the client is not found."
For this, there is a special response code called 404.
You have seen thousands of pages on the internet that say "Page not found—error 404."
That’s what we mean.
At this moment, when we come up with responses to requests, the analyst needs to sit down and think carefully about what cases might arise.
Perhaps they have cases that describe different scenarios, including alternative scenarios.
For example, if we requested a client that exists, we have a successful scenario with response 200.
If we requested information about a client who is not in the database, we should respond with 404, and there should be no body in the response.
If we requested information about a client who exists but the requesting system does not have access to it, we might respond with 403.
If we requested information about a client who exists but their profile is empty, we might respond with 200, indicating that the client was found, but return an empty JSON.
I’m just speculating on what other options might be.
Someone might try to enter without a password, and the response could be 401.
We can brainstorm and come up with these response options when non-standard situations occur, and it’s essential to describe them.
Alexander mentions 500 errors, but we analysts don’t design those; the server returns them when it’s not working.
At that point, it won’t be about business logic; it will just say, "I’m not alive."
Max comments that the case is not super clear, but okay.
As is customary, I accepted this feedback.
So, I’m fine with that.
Let’s summarize what we have done today.
We have reviewed the resolution of the broadcast at 720.
I believe this is set on your side.
It’s possible that the broadcast is at 720, but the recording may be of higher quality.
Thank you for dedicating this time.
Let’s summarize what we have accomplished today.
We remembered what REST is.
We looked at where to find indicators that integration is needed.
We now know where to look for integration requirements: in the requirements, in sequence diagrams, and in component diagrams.
To design, we need the ERD diagram describing the information model.
We need to know what actions will be performed on these entities and what the request-response exchange will look like.
We now know that designing an API or interface means coming up with a good URL and providing a good description that the developer will then implement.
We also glanced at how to document our API so that the developer can develop it and users can read and use it.
Great!
I remind you that our course on Systems Analyst specialization starts on the 31st, in two weeks, and you can still join if you wish.
One last request: I have a link that I will share in the chat.
I mentioned feedback earlier, and I encourage you to go to this link and write something about this session—what you liked, what you didn’t like, whether it was deeper or shallower than expected, or if it was more or less than you anticipated.
Your feedback is essential for improving our sessions and making our open lessons better.
Finally, feedback is needed to motivate the lecturer to share interesting content on camera every week.
Thank you all for your questions.
In about a day or two, this will be posted on YouTube on our channel, where you can naturally comment, and I will keep an eye on it for a while to answer your questions.
You can also move the discussion there.
It seems that’s all.
Thank you for making this not just a monologue but a session with questions and interesting ideas.
It’s great that you came prepared for this lesson.
Thank you all, and have a great Friday!